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Overview 


BRender is an extremely powerful real-time 3D graphics library, with a comprehensive Application 
Programming Interface (API), facilitating rapid and intuitive 3D development. 


The libraries have an elegant conceptual design throughout and are, as far as possible, platform 
independent. In brief, they provide functions and data structures relevant to the following areas: 
Hierarchical organisation of objects constituting a scene 

Lights, cameras and models 

Efficient handling of items in a ‘world database’ 

Texture and environment mapping 

Rendering, in a number of styles 

Scene picking and elementary collision detection 

Mathematical primitives, including: scalars, angles, quaternions, Euler angles, 

vectors and matrices. 

e Transparently selectable, fixed or floating point numeric representation 

e File systems, memory management and diagnostics 


Typically, a BRender application will perform the following tasks: 
e = Initialisation 

Importing or generating data (models, materials and textures) 
Rendering scenes 

Modification of object positions and orientations 

User interaction 


What is BRender? 


BRender is a rendering engine, the ‘bit of magic in the middle’ that turns a scene into an image. It is 
the TV camera of virtual reality, translating an abstract description of a set, with its actors, cameras 
and lights, into a picture on a screen. 


BRender is a combination of the most recent research in 3D graphics techniques and algorithms, and 
painstaking efforts to translate those algorithms into streamlined, lean, mean and highly optimised C 
code. Efficiency notwithstanding, BRender has always been designed with cross-platform portability, 
a wide range of useful features, and general purpose application, firmly in mind. 


BRender takes the form of a C library, a set of C headers and library files that you build into your 
application. This lets you concentrate solely upon the task of describing scenes, modelling them and 
presenting them to the user. BRender takes care of all the hard work involved in positioning items in 
a scene, lighting them, applying special effects, and from a given camera specification, working out 
what’s in the image, and rendering it (clipping, hidden surface removal, transparency, reflection, 
etc.). 


The BRender C Library not only provides access to the rendering engine, but also facilities at each 
end of the process: describing a scene and processing the resulting image. 
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BRender turns a description of a scene into an image 


Scenes in 3D worlds are described to BRender in terms of components called actors. Each actor 
represents a frame of reference in which geometric models (objects, shapes, polyhedra, etc.) and other 
actors can be positioned and oriented. This scene description often builds up to a fairly sizable 
hierarchical structure. 


Actors may perform a variety of different functions. There are three primary types of actor: model 
actors, which define shapes and their surface properties; light actors, which provide light with which 
models can be seen; and camera actors, which determine the viewpoint from which a scene is 
rendered into a 2D image. 


It is the application’s task to describe the scene in terms of an actor hierarchy, and BRender’s task to 
turn this description into a 2D image, 1.e. rendering it. However, although BRender is responsible for 
performing such rendering as efficiently as possible, the application is just as responsible for 
describing the scene as efficiently as possible. Both application and renderer must be optimised if 
high performance is to be achieved. BRender cannot compensate for a poorly written application. So, 
let’s work in harmony to help produce extreme, jaw dropping applications. 


Why is BRender so good? 


The development team behind BRender includes experts with considerable experience in various 
fields including: 3D scene description and modelling, 3D algorithms, 3D graphics hardware, video 
games development, advanced mathematics, compiler and microprocessor design. 


Intense research and development over the last few years has culminated in what we believe is the 
best portable, all-round 3D rendering system available. 
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Objective 


The BRender Technical Reference Manual is designed to provide a reference for the developer who 
has started working with BRender, and to answer as many questions about the technical details of the 
BRender API as possible. 


Audience 


This manual is for all users of BRender that require detailed technical information. It is not intended 
as a 3D graphics tutorial or C programming tutorial. 3D application developers and programmers will 
need to be fully conversant with contemporary 3D graphics technology (ideally also having an 
appreciation of the lower level aspects) and considerably experienced at C programming. 


Coverage 


This manual only covers the BRender API, it does not cover platform specific support libraries, 
hardware or performance issues, nor does it provide introductory or tutorial material. Although it may 
provide some background, or suggestions for use, the manual is primarily concerned with providing 
reference documentation. 


Organisation 


Given that this manual is likely to be used from beginner as much as expert or intermediate, there is 
inevitably a compromise that has to be made in how the manual is organised. While the beginner 
might appreciate a step by step, procedural oriented manual (getting gradually more sophisticated 
through the pages), an expert might prefer everything arranged alphabetically as a pure reference. 
‘The compromise we have made is to have an initial section which describes the API in a structured 
way, with each aspect described in context, followed by a section with data structures in alphabetical 
order and the set of functions relevant to them. This is suitable for the intermediate to advanced 
developer, who has got up to speed with BRender, but doesn’t yet know it inside out. Thus, a more 
structured organisation (than purely alphabetical) is required, but not so structured as to impede 
location. There is always going to be a steep learning curve for such a complex product as BRender, 
so introductory and tutorial material has been supplied separately. 


Note that while the installation guides cover some technical material associated with particular 
platforms, the BRender API is covered in a single volume and includes all the inevitable platform 
variations. This is useful for giving an appreciation of the differences between function and 
performance across platforms, and should encourage developers to cater for such variation at the 
design stage. 
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The API Function 


Each BRender function is described in a structured way using the following sub-headings: 


Description 
Declaration 
Arguments 
Preconditions 
Effects 

Result 
Remarks 
Example 

See Also 


The Data Structure 


The function is briefly described 

The simple C declaration 

Each argument or parameter to the function is described 

Any entry conditions are detailed 

Any effects (apart from producing a possible result) the function has are described 
The function result is described 

Any remarks concerning caveats, possible uses, misunderstandings, etc. 

A brief source code extract placing the function usage in context 


Any data structures or functions that may be of relevant interest 


Each BRender data structure is described in a structured way using the following sub-headings: 


The Structure 
The Integral Type 
The Call-back 
Function 
Members 
Specification 
Operations 


Arithmetic 


Comparison 


Conversion 
Copy / Assign 


Access & Maintenance 


Referencing & 
Lifetime 
Initialisation 
Construction & 
Destruction 


Supplementary 


Import & Export 


Platform Specific 


Copyright © 1996 Argonaut Technologies Limited 





The data structure isa C struct data type 
The data structure is a basic type, based on a fundamental type such as int or long 


The data structure describes a function pointer, usually for a call-back function 


Public members of structures are described in detail 
The task of a call-back function is defined 
Functions operating upon one or more instances of this structure or type 


Operations enabling this structure or type to be operated upon as though it were a simple 
type such as int 


Functions providing a means to quantitively compare two instances of this structure or 
type 

Functions converting this structure or type into another 

Methods and functions to use to assign or duplicate this structure or type 


How the data structure or type is accessed and maintained by BRender and the 
application 


How the data structure can be referenced, and how long it should be maintained by 
BRender and the application 


How the data structure or type can be initialised 


How the data structure should be created in memory and destroyed 


Informational functions available for the data structure, not particularly concerned with 
its function 


How the data structure may be created from, or written to, an external file 


Any platform specific differences relating to this data structure or its functions 


Using this Manual 


It is a good idea to skim through the entire manual first, just to familiarise yourself with the API. If 
you have a particular question concerning an aspect of the API, try to locate relevant documentation 
in the manual using the contents, function index, full index, or by leafing through appropriate 
sections. All functions and data structures have a subscript cross-reference to the page number on 
which they are described. 


‘Typographic conventions 
Throughout this manual, syntax, arguments, definitions and example code are in a typewriter-like 
font, to distinguish them from normal text. For example: 
void BrTransformToTransform(br_transform *dest, const br_transform *src); 
or 


BR_ACTOR_CAMERA 


Most public BRender functions have names of the form BrFunctionName (), i.e. with a prefix ‘Br’ 
and a case-separated name’. Most public BRender data structures have names of the form 
br_structure_name, i.e. with a prefix br_ and an underscore separated name. 





* Note though, that due to historical precedent, pixel map is considered a single word in function names, thus 
BrPixelmapCopy (). 
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Library Initialisation & Termination 


Library Initialisation & ‘Termination 


Initialisation 


The BRender library requires more than static initialisation, and needs an opportunity to perform 
various initialisations before most BRender functions are called. There is, as yet, no standard for 
library initialisation, so the function BrBegin () ,, is provided as a means of explicitly initialising the 
BRender library. 


However, there are a few things that should precede BrBegin () ,,, and in the following order: 

1. Install a diagnostic handler using BrDiagHandlerSet () ,,, (See Diagnostic Support, page 66) 
2. Install a memory allocator using BrAllocatorSet () ,; (See Memory Management, page 54) 
3. Install a filing system using BrFilesystemSet () ,,, (See Filing System Support, page 58) 


If any of these steps are not performed, BrBegin () ,) will perform the equivalent to a usable default 
(appropriate to the platform). Which steps you perform depends upon your application’s 
requirements. 


BrBegin () 
Description: Initialise BRender. This function must be called before most BRender functions 
are used. 
Declaration: void BrBegin (void) 


Preconditions: — Static initialisation has completed (main() has been entered). The BRender 
library has not yet been initialised, or has been terminated. 


Effects: Installs any missing handlers (diagnostic handler, memory allocator, filing system) 
to appropriate platform defaults. 


Initialises filing system (See Filing System Support, page 58) 
Initialises registry (See Pre-Rendering Pre-Processing, page 29) 
Initialises resource classes (See Resource Management, page 49) 


Creates various defaults (models, materials, etc.) 
Remarks: Do not call BrBegin(),. again without a preceding BrEnd () ,,. 
See Also: BrEnd(),, 


‘Termination 


The BRender library should be closed down when it is no longer required (having first ensured the 
application has explicitly released all use of BRender facilities). This typically causes BRender to 
release all memory allocated in resource classes. Nevertheless, it may still be restarted using 
BrBegin () ,, (though handlers do not necessarily need to be reset). 
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BrEnd () 


Description: 


Declaration: 


Preconditions: 
Effects: 


Remarks: 


See Also: 


Library Initialisation & Termination 


End BRender, freeing its internal resources and memory. 
void BrEnd (void) 
‘The BRender library has been initialised and has not already been terminated. 


Releases all memory allocated in resource classes. This is effectively all memory 
allocated by BRender for its own use and all memory allocated in the various 
BRender allocation functions, such as BrModelAllocate () 5,;. 

Your application should have gracefully released all dependence upon BRender 
data and functions before calling BrEnd () ,,. 


BrBegin () , 
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Scene Modelling 
The Actor 


See br_actor,, 


Scenes are described in terms of actors’, typically used to place models, lights and cameras. Nothing can 
see or be seen ina scene without actors. Of course it is still possible to perform 2D operations, such as 
copying a backdrop into a screen pixel map, or plotting text, but BRender’s 3D effects are all obtained 
via actors. 


The actor is intrinsically, just a means of orienting and positioning something with respect to 
something else. Thus a scene is organised around a system of actors. Admittedly, most actors are used 
to place models (visible shapes), but they can be used for a variety of other purposes, such as placing 
lights and cameras, and defining common frames of reference. 


The function BrActorAllocate(),, is one of the many ways of creating an actor. 


Hierarchical Relationships 
See br_actor,,{next, prev, children, parent, depth} 


A scene is described in terms of a single actor, however, that actor can be augmented by any number 
of other actors, which can be similarly augmented in turn. This gives rise to the tree-like, hierarchy 
of actors describing a scene. It is often described as though it were a family tree, with terms such as 
parent, child, and sibling used. 


The br_actor,, has various members defining its hierarchical relationship. The next and prev 
members describe a linked list of siblings, parent and children are self-evident and depth is 
equivalent to the generation of the actor. 


The actor hierarchy is built up using functions such as BrActorAdd () ,. Naturally, there will be some 
occasions when the structure must be modified, and functions BrActorRemove (),,; and 
BrActorRelink(),; are provided for this purpose. 


Positional Relationship 
See br_actor,,{t}, br_transform,,, 


Descendants, in additional to their hierarchical relationship, also have an associated positional and 
orientational relationship with their parent. An actor’s position and orientation is defined solely with 
respect to its parent, rather than being relative to some absolute co-ordinate space. For some, this has 
drawbacks, but most applications benefit from the ease with which complex systems of inter-related 
models can be positioned. If an absolute frame of reference is required then actors can all be made 
children of the ‘universe’ parent. 


When rendering BRender applies a general affine transformation, starting at the tree’s root, between 
each actor and each one of its children. As the tree is traversed, the transformations are accumulated. 
This means that a simple modification to one actor’s transform will affect the position and orientation 


* The reason for the term ‘actor’ rather than ‘object’, is due to the possible confusion that might arise if ‘object’ 
was used, especially in these days of object oriented technology. Try thinking of the scene as a stage or film set, 
with ‘actor’ as a natural, umbrella term for each of the individual elements making it up. 
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Scene Modelling 


of all its descendants. Note that the root of the hierarchy has no parent, and consequently, its 
transform has no meaning. 


The transformation matrix that can be used to transform co-ordinates in one actor’s co-ordinate space 
into that of another’s, can be obtained by using the function BrActorToActorMatrix34 () «4. 


Functions 


Seebr_actor,,{type, type_data,model,material, render_style}, br_model,,,, 
br_material,,, 

While actors should be thought of as elements in a structure of relative frames of reference, actors can 
be set to perform specific functions. Usually this is to be a place holder for a model (scenery or props, 
say). 


There are three primary types of actors: models, lights and cameras. Models are visible 3D shapes 
defined in terms of geometry (vertices and faces) and surface (colour and materials). Lights are 
invisible actors that cause lighting effects upon models’ surfaces. Cameras are invisible actors that 
define a particular viewpoint and perspective from which to view a scene. 


There are various other functions an actor can provide, typically for assisting BRender by reducing 
unnecessary rendering. 


The smallest hierarchy that will produce an actual rendered scene consists of four actors, namely a 
root, a model, a camera and a light source. The root actor is patently at the root of the hierarchy, and 
the model, camera and light actors are its children. 


The Reference Actor 
See br_actor,, {type} 





This actor type specified by the symbol BR_ACTOR_NONE, is typically used to assist the layout and 
organisation of a hierarchy. Although every actor defines its own frame of reference (co-ordinate 
space), for this actor that is all it does. 


In spite of its lack of specialisation it still serves a useful purpose. For instance it may be convenient 
to represent a flock of birds with each bird positioned relative to some notional position of the flock, 
and then simply move the flock as a whole’. The position of the flock could be defined by a reference 
actor, and each bird a child model actor. 


In general this type of actor is very useful when direct and independent control is required of each 
stage in a complex transform that needs to be applied to a model or system of models. Rather than 
recalculate this transform each time, each stage (typically very few) can be represented by a separate 
actor. For instance a reference actor could represent a translation and rotation, while the child model 
actor could be solely concerned with scaling the model. 


Invariably, the root of a hierarchy will be a reference actor. 





* Forgiveness being begged from those conducting painstaking research into flocking behaviour. 
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The Model Actor 


Seebr_actor,,{type, type_data,model,material, render_style}, br_model,,,, 
br_material,,, 

The model actor is what it’s all about; the linchpin of all 3D rendering — no scene should be without 
one. 


As stated earlier, models are visible 3D shapes defined in terms of geometry (vertices and faces) and 
surface (colour and materials). A model actor is primarily defined by its model member, but also has 
the material member to define a default material to be used for parts of the model’s surface that 
don’t specify a material. The render_style member can also affect things by rendering the model 
in different ways. Some of these ways can be useful for things such as selection highlights or simple, 
but rapid rendering, e.g. wireframe style. 


A feature of model actors is that they can inherit properties such as model, material and rendering 

style from their ancestors. Thus a flock of birds could consist of the same model, but have varying 
materials. If the model was changed then all birds would change. Note that the model, material 
and render_style members are still effective for purposes of defining inheritable model actor 

properties in other actors (even of type BR_ACTOR_NONE). 








Create a model actor using BrActorAllocate (BR_ACTOR_MODEL, NULL).,, then assign a model to 
the actor’s model member. 


The Model 


See br_model,,, {vertices, faces}, br_vertex,,,, br_face,,, 


The model is defined by a list of vertices and faces. Each vertex defines a vector from the model 
origin to a corner of a face, typically shared by two or more faces. Each face, representing a part of the 
surface of a model over which a material is rendered, is defined in terms of a series of vertices. Thus 
a cube can consist of eight vertices and six pairs of co-planar triangular faces, with each face specifying 
three vertices. 


The model’s geometry can be continuously modified, enabling powerful effects such as deformation 
and morphing. Because BRender may optimise a model’s geometry, if you need to make 
modifications, you will generally need to retain the vertex and face data as originally specified, there 
are flags to control this such as BR_MODF_KEEP_ORIGINAL. 














BRender maintains some useful information about models, such as their bounding radii and bounding 
boxes (see radius and bounds of br_model.,,,). 


Create a model using BrModelAllocate () ,,,, ensuring that the model is added to the registry 
(BrModelAdd () »,.) before the actor hierarchy is rendered. 


The Vertex 
See br_vertex,,, {po}, br_vector3,,, 


The vertex defines a point within a model’s co-ordinate space that may be referred to by faces. By 
changing this point, faces referring to it will also change. The number of vertices in a model can be 
specified at the time the model is allocated. 
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The Face 


Seebr_face,, {vertices}, br_model,,, br_vertex,,, 


The face defines itself in terms of a polygon, typically a triangle, with vertices specified by indices 
into the vertices list within the model. The order in which they are specified is important; it 
specifies the perimeter of the visible side of a face, going anti-clockwise around it. It doesn’t matter 
which vertex is specified first. 


The face also defines the way in which its surface should be rendered, by specifying a material. 


The number of vertices in a model can be specified at the time the model is allocated. 


The Material 
See br_material,,,{flags,ka,kd,ks,colour}, br_colour,,, 


Materials define exactly how faces should be rendered. This can be anything from a single colour 
value to a lit environment map. It all depends upon how realistic the surface is required to be, how 
much it should be influenced by lighting conditions, and the complexity of the colouring. 


Materials are so called, because it is expected that most models represent physical materials such as 
wood, granite, wall-paper, etc. Predictably, the more realistic the material is required to be, the 
greater the processing overhead is likely to be. Nearly all the parameters of BRender materials are 
concerned with making a compromise between quality and performance. The simplest material is 
defined simply in terms of a colour value, and is not subject to any lights in the scene; this gives 
cartoon-like materials. Lighting effects can be added by specifying that the material is litand smooth 
shaded; this is suitable for materials such as plastic and painted walls. Textured materials such as 
wood and marble, can be represented using texture maps, and can also be affected by lighting. 


Naturally, the more processing that can be done beforehand, the less that needs to be performed 
during rendering. For this reason BRender provides the ability to specify prelit materials. This 
feature can be utilised in situations such as outdoor scenes, where the sun moves relatively slowly and 
thus need not be involved in frame by frame lighting calculations. Of course, things frequently 
changing orientation in the scene will still need to be lit normally. 


Lighting 


A model’s material can be affected by lights in a scene. The material’s colours will effectively appear 
dimmer or brighter according to how well they are lit. This will depend upon the surface’s orientation 
with respect to the viewer and each light in the scene. 


BRender uses the Phong lighting model. The following formula shows how the lighting A of a face 
depends upon 9, the angle at the face between the light source and the face normal, and 9, the angle 
at the face between the viewer and the reflected light ray. 

cos’ 


N= Kambient + k aipfuse©0S9 + E ecutat 


The ambient factor is the amount of light assumed to be reflected from other objects and lighting in 
general. Zero can produce a material whose illumination is highly dependent upon light sources, 
whereas higher values can give ever fluorescent or luminous effects. A typical sunny scene might have 
most materials with a significant ambient contribution, whereas a dusk scene might have a much lower 
one, and a moonlit one, probably zero. 
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The diffuse factor determines how much of the reflected light is made up of the component 
dependent upon the angle of the face to the direction of the light illuminating it. The closer the face 
comes to being perpendicular to the light source, the more light the face receives, and thus the more 
diffuse light that can be reflected. Zero can give a shiny surface, whereas higher values can give 
surfaces a more matt appearance. 


The specular factor determines how much reflected light is made up of the component dependent 

upon the angle between the reflected light source and the direction of viewer (naturally, if the angle 
is zero, the component will be at its maximum). The greater the value, the more prominent highlights 
will be. There is also the power of the cosine, and the greater this is, the sharper any highlights will be. 


Colours 
See br_colour,,, 


BRender has an integral type dedicated to the task of completely defining a particular colour. It is 
used directly when specifying true colours, which is taken to mean any non-indexed colour (one not 
utilising a palette). Colour can either be taken to mean the colour ofa screen pixel, the colour of light 
a surface reflects, or the colour of a light source within a scene. 


The colour structure is currently 32 bits, made up of three (or four if you include an alpha component) 
bytes. You can construct a colour using the BR_COLOUR_RGB() macro. 


‘The Shade Table 


See br_material,,,{flags, index_base, index_range, index_table, colour_map}, 
br_pixelmap,,, 

For performance reasons (with the added benefit of lower memory requirements) textures, rendering 
or both can be performed using colour indices instead of colour values. Each colour index is converted 
into a colour value using a colour look up table (CLUT), often called a palette. When textures are 
made up of indices there is no straightforward way of lighting them. The brute force way would be to 
look up each texture index in the colour table, apply lighting to it to see what shade it should be, and 
then search through the colour table for the index of the colour value most closely matching this shade 
(which may not be very close at all). Because there isn’t any processing power to waste, BRender 
implements a scheme using a shade table which for a given colour index and proportion of light, will 
give a colour index corresponding to the shaded colour of the original index. 


Being two dimensional and storing pixel values, the shade table is quite suitably represented in the 
form of a pixel map. It has as many columns as there are colour indices and as many rows as there are 
distinct shades (from unlit to fully lit). 


A shade table is created as a pixel map, commonly of type BR_PMT_INDEX_8, when rendering in 256 
colour modes, for indexed textures with 256 columns (2° for textures of type BR_PMT_INDEX_8) and 
64 rows. Use BrPixelmapAllocate (BR_PMT_INDEX_8, 256,64, NULL) 5, not forgetting to call 
BrTableAdd(),,; before it is used in rendering. 











Tools are generally available to take the effort out of making shade tables. 


The Texture Map 


See br_material,,,{flags, colour_map,map_transform}, br_pixelmap,,, 
br_matrix23,,, 


For textured materials, there is an additional problem of how a model’s surface should be covered. 
This is a bit like the reverse of how to lay a map of the world on a flat sheet of paper. Similar, but 
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while textures are effectively flat, models are hardly ever spherical (even ellipsoid). When it comes 
to wrapping textures around complex models, tools are essential. 


When it comes to library facilities, BRender provides a general mapping transform (how the flat texture 
should be warped to cover each face) and texture co-ordinates at each vertex (defining the coverage of 
the infinitely tiled texture plane by each face). There is also an option as to whether textures should be 
perspectively correct or not (a compromise between performance and warping). A feature of texture 
maps in BRender is that the texture map transform can be continuously modified, thus providing 
animated surfaces for insignificant performance overhead. 


A texture can even be produced by from a scene rendering. This can provide effects such as television 
screens and rear view mirrors. It can be extended further in combination with the environment map 
(a first reflection ray trace) to provide mirrored surface effects. Remember though, that fast rendering 
is not only a product of efficient rendering algorithms, but also upon the application programmer’s 
skill at reducing its workload. For instance a wall mirror could have the rest of the room’s reflection 
precomputed into a texture map to be used as an environment map. If passers-by should also be 
reflected, then all that’s required is a rendering of just the passer-by over this map (from the mirror’s 
point of view). 


A reflective effect is often a good substitute for a reflection. Christmas tree baubles for instance can 
be environment mapped without really needing to reflect any movement by anything else. 


A texture map is created as a pixel map, usually with dimensions being powers of two. If an index 
texture map is used that will be lit, then remember to supply an appropriate shade table as well. To 
create a texture map use BrPixelmapAllocate(),. followed by BrMapAdd ().s,; before it is used 
by a rendered material. 


The Light Actor 


Seebr_actor,,{type, type_data}, br_light,,,, br_material,,, 


While models are the only visible elements of a scene, as in reality they require light in order to be 
seen. For this reason light actors may be used to position and orient lights within a scene. Lights are 
not visible even if looked at directly. Or course, a brightly prelit model can be made a child of the 
light — thus making a fairly realistic spotlight model. Note though, that models are transparent to 
lights (without computationally intensive shadow processing, anyway). 


If light actors are not used, there are only two ways of making surfaces visible. These are pre-lit 
textures and ambient lighting. For prelit textures pre-computed lighting levels at each vertex are 
stored in the vertex data structure and the BR_MATF_PRELIT flag specified with the material data 
structure. This is fine for relatively stationary models (such as buildings) that are primarily lit by 
relatively stationary light sources (such as the sun). Ambient lighting only, is really only appropriate 
for models that are moderately and evenly lit from all directions, but where this lighting level can 
change, e.g. ceilings in well lit rooms with ‘dimmer’ light controls, or outdoor scenes with ambient 
lighting affected by cloud cover or nightfall. 





Having all the control of the actor of which they are a part, light actors’ position and orientation can 
be fully controlled. This greatly facilitates situations requiring moving lights such as: roving spot 
lights, sun-rises and sunsets, headlights moving with the car, etc. 


Light actors can be created using BrActorAllocate (BR_ACTOR_LIGHT, NULL),,. A light 
specification will automatically be allocated and pointed to by the type_data member of the actor. 
Of course, an instance of abr_light,,, structure can be conventionally created and supplied as the 
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second argument instead of NULL. Note that light actors will need to be enabled for their lighting to 
affect the scene (see BrLightEnable () ,). 


The Light Specification 
See br_light,,,{type, colour}, br_colour,,, 


Lights come in various forms. The simplest light is a direct light, which has the effect of a light a long 
way off, such as the sun or moon, or in some cases a flood-light. It certainly won’t be very good for effects 
such as a candle lit scene. That sort of thing is a job for the point light, which can also be used for things 
such as light bulbs, fires, street lights, etc. For more precise control of light, the spot light may be used. 
That can be used, predictably enough, for such things as spot lights, search lights, torches, head lights, 
light-houses (where the beam runs along a cliff face say), etc. 


Point and spot lights can also be controlled in terms of how rapidly their light diminishes over 
distance (attenuates). This is useful for candles and head-lights, i.e. a candle doesn’t light up much 
more than the immediate vicinity, and objects in the path of head lights get brighter as they get 
nearer. 


The spread of spot lights can also be controlled in terms of an inner fully lit cone and an outer 
penumbral cone between which the light tails off. Note that spot lights are really conically limited 
point lights, rather than diverging (or converging) from a sized disc. This difference will need to be 
appreciated when it comes to implementing cylindrical lights such as lasers and search lights, the laser 
is probably better implemented using the BrScenePick3D (),, function, locating the face and point 
of illumination and then directly modifying the screen pixel (found using 
BrActorToScreenMatrix4 () x). 


Light specifications can be created automatically at the time the light actor is created, or they can be 
created conventionally. 


The Camera Actor 
See br_actor,,{type, type_data}, br_camera,,, 


There is a third ingredient to a scene, given a model to see and light to see it by, and this is an eye to 
see it with. Given our familiarity with photography and television, it is more useful to think of this 
eye as a camera that relays its image to our computer’s monitor or TV screen. Then we have no 
problem with the possibilities of having more than one camera in the scene at the same time. Each 
camera defines how a 2D image is produced. Each image is invariably stored on a pixel map of 
particular dimensions. These images are then either incorporated into the 3D scene or another 2D 
image. Eventually, a 2D image will be produced for display on all or part of the screen. 


‘The camera actor’s position and orientation can like any other actor be continuously positioned and 
oriented. This allows things such as a driver’s view round a race track, a bird’s eye view, a fly-on-the- 
wall view, and any other view you can think of. Cameras are also useful for creating reflections and 
mirror views, T'V screens, and crude shadow and lensing effects. 





Camera actors can be created using BrActorAllocate (BR_ACTOR_CAMERA, NULL)». A camera 
specification will automatically be allocated and pointed to by the type_data member of the actor. 
Of course, an instance ofa br_camera,,, structure can be conventionally created and supplied as the 
second argument instead of NULL. 
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The Camera Specification 


See br_camera,,{type, field_of_view, aspect} 


There are two basic types of camera, the parallel camera and the normal perspective one. The parallel 
camera produces an isometric image, i.e. faces are not scaled in the image according their distance 
from the viewer. The perspective camera on the other hand, according to its field of view, can range 
from ‘almost parallel’ to a fish eye lens effect (180° field of view). Somewhere in between we get a 
conventional view. If you wished to consider the screen as a window onto a virtual world, the field of 
view would be the angle subtended at the eye by the top and bottom of the screen. Of course, it 
depends how far away you are, but it can typically be between 10° and 40°. Given frequent exposure 
to the cinema and television screen, most people are quite happy with the larger end of the scale. 


Note that the aspect of the camera must be specified to ensure that what is square in a scene remains 
square when it is displayed on the screen. Calculating the aspect boils down to simply measuring the 
physical width of the output image and dividing it by the physical height. In the process of producing 
homogenous screen co-ordinates, which are mapped to the full width and height of the output pixel 
map, the original x axis is scaled down by the camera aspect (see BrMatrix4Perspective () ,,). The 
formula to compute the aspect is thus: 


Screen Width S,,, 
Pixel Map Width P,, Horizontal Resolution H,,. P, S,V,., 


Pixel Map Height P,, a Screen Height S$, Pp i SH es 


Vertical Resolution V,,,, 


Aspect = 





So if you have a screen measuring 8"by 6", which has a horizontal resolution of 320 and vertical 
resolution of 240, and you are rendering to an image 120 pixels across by 100 pixels high, then the 
aspect is obtained as follows: 


1920 _ 


1.2 F959 = 


12 24 
Aspect, = ee 1.2 


= 100 *6x320 ~ 


You’ll notice that if a screen has square pixels (as in the above example) that the camera aspect simply 
needs to be the width of the output image divided by its height. The reason why BRender doesn’t 
perform this calculation itself and have the ‘aspect’ as the ratio between the sides of the physical 
pixel, is because the image pixel map is assumed to be the same shape as the screen — how many 
pixels are on each edge, in BRender’s view, is simply a matter of resolution. 


Most camera views need to be in perspective, but there are a few good uses for parallel views other 
than for viewing CAD models: projecting sun shadows onto walls, creating height fields in depth 
buffers (camera looking down), creating aerial maps, telescopic views, etc. Parallel views can be sized 
using the width and height members (not forgetting the influence of aspect). 


Remember, the camera does not have to be reserved for the player’s view. 


Camera specifications can be created automatically at the time the camera actor is created, or they can 
be created conventionally. 
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Other Actors 


Seebr_actor,,{type, type_data} 


There are three other functions actors may perform. These are primarily concerned with assisting 
BRender in reducing unnecessary processing. The bounds actors are ways of saving BRender from 
performing some of its usual ‘on screen’ or ‘off screen’ checks for models. The clip-plane actor is a 
way of selecting out model actors that although are in the view volume, are not required in the image. 


These other actors are created in a similar fashion to other actors, e.g. using 

BrActorAllocate (BR_ACTOR_BOUNDS, NULL),,. A bounds or clip-plane specification will 
automatically be allocated and pointed to by the type_data member of the actor. Of course, an 
instance of the specification structure can be conventionally created and supplied as the second 
argument instead of NULL. Note that clip-plane actors will need to be enabled before they affect the 
scene (see BrClipPlaneEnable () ,,). 


The Bounds & Bounds Correct Actors 
Seebr_actor,,{type, type_data}, br_bounds,,, {}, br_vector3,,, 


Bounds actors are a way for the application to assist the renderer in removing the necessity for many 
on/off screen’ checks. Bounds actors only affect rendering in terms of enabling or disabling rendering 
of descendant model actors, they are not a visible part of the scene’. It is up to you to calculate the 
co-ordinates of the bounding box, BRender does not do this automatically, although you could 
possibly exploit the model’s bounding box that it does calculate (upon BrModelUpdate () ,,,). As long 
as you ensure that the co-ordinates of each model’s bounding box are transformed into the bounds 
actor’s co-ordinate space, they can all be accumulated as appropriate. 


You should use bounds actors for complex systems of models that have relatively compact 
configurations, or systems of models with models that do not need to be drawn if a certain, primary 
model is not visible, e.g. selection controls. The difference between BR_ACTOR_BOUNDS and 
BR_ACTOR_BOUNDS_CORRECT is that the latter represents a guarantee to the renderer that there is 
no surface of a descendant model that projects outside the bounding box. If there is any chance that 
a descendant actor’s model may protrude use BR_LACTOR_BOUNDS, as the undefined behaviour 
resulting from the use of BR_LACTOR_BOUNDS_CORRECT includes anything, not necessarily just 
corruption of the screen, or aborting. 











Note that in the cases where, in spite of using bounding box actors, the renderer neither knows that 
a model is entirely off screen nor entirely on screen, that the model’s bounding box is used to 
determine whether the model should be rendered (or its call-back called). If the model is partially or 
wholly on screen, each face is clipped against the viewing volume and enabled clip plane actors. 


The Clip-Plane Actor 

Seebr_actor,,{type, type_data}, br_vector4,,, 

Clip-plane actors in single-pass rendering are really only good for rendering simple effects such as 
crude cross-sectioning and selective lighting. For an example of selective lighting consider a room 
with a single spot-light being the only form of illumination. It is sometimes quicker (with a lot of 


On screen is defined as within the viewing volume and in front of all enabled clip planes. 
+ Do not be confused by BR_RSTYLE_BOUNDING_POINTS, etc. The bounding box referred to there is the one 


calculated by BRender, referenced within the br_model data structure. 
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objects in the room) to define a conical region with three clip-planes than solely rely on the 
attenuation of the spot-light to select-out unlit faces. Thus only objects entering the spot-light 
pyramid (and the viewing volume) will be visible and lit by the spot-light. 


Clip-planes really come in to their own when used in multi-pass rendering. Shadows (as opposed to 
silhouettes) can be implemented by rendering one sectioned part of a scene with a direct light, and 
the other unlit (using only the ambient component), e.g. similar to the spot-light example above, a 
window frame could be used to define a fully lit pyramid using four clip-planes. The fully lit 
rendering has the planes facing inward, the shade rendering has the planes facing outward. Another 
lighting effect is a sunset (setting over a flat horizon such as the sea) where the tops of trees, buildings 
and hills are fully lit, and one or more lower sections have deeper hued and darker lights. A more 
obscure trick would be to use a clip plane to define the surface of a pool and render the pool and its 
contents slightly differently, possibly even using a different camera position to produce a refraction- 
like effect (though this would require rendering the pool image to an intermediate texture map). 


Clip planes are not recommended as a way of pruning large actor hierarchies’. Clip planes are 
intended for their clipping effects, not their pruning effects. 


A clip plane is defined by a four-vector. This is made up of a three-vector, being the unit normal to 
the plane, and the offset of the plane from the origin (in the direction of the normal). The equation 
of the plane is given as the dot product of this four-vector and the homogenous co-ordinates of a point 
on the plane, being equal to zero. Thus: 


n,’P, = 9 


Where n, is the four-vector defining the plane in terms of a unit normal and offset, and P,, is a point 
on the plane. 


Descendants’ faces are clipped against the plane, with the side defined by the normal being ‘in 
scene’. 


Note that clip-plane actors will need to be enabled before they affect the scene (see 
BrClipPlaneEnable () ,,). 


Co-ordinate Spaces 


While this manual requires understanding of 3D graphics, so much confusion arises out of the variety 
of co-ordinate spaces, that a discussion is worthwhile - even in this document. BRender itself, only 
really ever deals with three co-ordinate spaces, those of the model, the view, and the projected screen. 
Nevertheless, it is often useful for the 3D applications developer to have other co-ordinate spaces in 
mind. 


During rendering, every model’s co-ordinate space is transformed through accumulation of actor 
transforms into the view space, and thence to projected screen space: primitive vertex data, pixel and 
depth co-ordinates. 


Of particular note to those beginning 3D graphics: BRender has no concept of a world co-ordinate 
space (an absolute frame of reference). 





* Actor hierarchies should be organised according to visibility so that pruning can be performed directly, rather 
than by using a clip plane. 
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Model co-ordinate space 


A geometric model consisting of vertices, and faces between them, has its own local right-handed co- 
ordinate system. There is an implicit origin at (0,0,0)". An untransformed model, as seen by an 
unrotated camera (translated along its positive z axis so it faces the model), will have its positive axes 
pointing as follows: x to the right, y upwards, and the z pointing toward the viewer. A unit of 1 in the 
model will remain a unit of 1 in the view space unless any intervening actor transform involves a 
scaling. 


Actor co-ordinate space 


The actor co-ordinate space is shared by its model (if it has one), but is relative to its parent actor’s 
co-ordinate space through the use of a transform. The actor transform is defined as the transform 
which must be applied to points in the actor’s co-ordinate space (of its model’s vertices, say) for them 
to represent the same points in its parent actor’s co-ordinate space. 


World co-ordinate space 


Whether there is any notion of an absolute frame of reference, or co-ordinate space, is entirely up to 
the application. It may be appealing to think of a root actor as defining a world co-ordinate space, but 
this is entirely arbitrary, as BRender treats the root actor like any other. The root actor is so called, 
because it represents the immediate parent of each actor supplied for rendering (e.g. using 
BrZbSceneRenderAdd () ,,), and the ancestor of the camera used for rendering. Its co-ordinate space 
is certainly not special. Of course, the root actor’s transform is redundant as the co-ordinate space of 
its parent (if it has one) is never used (for a given rendering). 


Camera co-ordinate space 


The only actor whose co-ordinate space might be regarded as special is that of the camera actor used 
for a particular rendering. It is into this actor’s co-ordinate space that every model is transformed* 
(during rendering). See br_model_custom_cbfn,,, for details of transformation matrices and 
functions that can be used to convert model co-ordinates into view space, or screen space. The use of 
the term ‘view space’ is preferred to ‘camera space’. 





View space 


View space is effectively the camera co-ordinate space, the co-ordinate system in which the view 
volume is defined. The view volume is the section of the pyramid* defined by the camera’s field of 
view from -hither_z to -yon_z, and aspect ratio, aspect. It is further defined by the origin of the 
output pixel map, origin. Note that the sides of the view volume correspond with the sides of the 
pixel map irrespective of its own aspect, therefore the camera’s aspect is the only means of ensuring 
a correct aspect ratio is maintained. 


* Though br_modeL1 has a pivot point which enables translation of the model origin. 

+ Effectively, anyway. Whether a model’s vertices actually exist in this co-ordinate space at any moment is 
implementation dependent. 

~  Arectangular prism if using a parallel camera. 
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Homogenous screen space 


An intermediate phase in the transformation between view space and projected screen space is that 
of homogenous screen space. This is the viewing volume transformed into a cube, still with a right 
handed co-ordinate system, defined between (left, bottom, near) (-1,-1,+1) and (+1,+1,-1). 


Projected screen space 


Projected screen space is the homogenous screen space transformed into co-ordinates suitable for 
rendering to the screen. That is, the x and y limits will correspond to the bounds of the pixel map, 
and the z limits will be mapped to the range [-32,768,+~32,767.9]. There are various functions dealing 
with such values, e.g. BrZbScreenZToDepth () ,,, BrOriginToScreenXYZO () 55. 


The projected screen space is still a right handed co-ordinate space, but the positive axes now point 
as follows: x right, y down, and z away from the viewer. 


When ‘screen space’ is referred to, i.e. without any qualifier, it should be assumed that ‘projected 
screen space’ is intended. 


Physical screen space 


There isn’t really a physical screen space, but it can be thought of as the projected screen co-ordinates 
converted into values used directly by the rendering engines, i.e. x & y converted to integer pixel map 
co-ordinates, and z converted to z buffer depth or z sort depth. 


Converting between Co-ordinate Spaces 


It is often necessary to convert from 3D space to 2D screen co-ordinates and vice versa. There are 
various functions that can assist in this. BrMatrix4Perspective ().. will produce the matrix 
transformation that transforms view space (of a notional camera actor) into homogenous screen space 
(assuming a perspective projection). It is often more convenient to have a transform between an 
actor’s co-ordinate space and the homogenous screen space, and BrActorToScreenMatrix4 () x is 
provided for this purpose. 


There are more extensive screen oriented functions available for use within custom model rendering 
call-backs (see br_model_custom_cbfn,,,). These are basically, functions to convert model co- 
ordinates into screen co-ordinates (BrPoint ToScreenxY () ,;;), and a function to determine whether 
a model is on screen (BrOnScreenCheck () };,). 


The homogenous screen co-ordinate space is a cuboid defined between (left, bottom, near) (-1,-1,+1) 
and (+1,+1,-1). The projected screen co-ordinate space is defined such that the scalar 2D x and y co- 
ordinates range across the output pixel map, i.e. between (left top) (-origin_x, -origin_y) and 
(width-l-origin_x, height-1l-origin_y) and the z ordinate lies in the range (near to far) [- 
32,768,+~32,767.9]. 


There is an inverse relationship between z values in the view co-ordinate space and projected screen 
space z values. The conversion from a view z ordinate g,,,,, to the corresponding projected screen z 
ordinate Screen, is given by: 
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15 Pb ont hithee = ple aon + Cinee) 
Screen, = —2 > -§ ————— 
Zien = Ziither) 


This result is the expansion of applying the transform obtained from BrMatrix4Perspective () ».5 
to a z ordinate, and then multiplying the result by -2"°. 


Note that z buffer and z sort depth values are not necessarily the same as projected screen space, z 
ordinates. Functions are available to convert between depths, projected screen space and camera co- 
ordinate space. 


BrScreenZToCamera () 


Description: | Convert screen z [-32,768,+~32,767.9] to view z 
{[-hither_z,-yon_z]. 


Declaration: br_ scalar BrScreenZToCamera(const br_actor* camera, 
br_scalar sz) 


Arguments: const br_actor* camera 
Pointer to camera actor. 
br_scalar sz 
Screen z value, e.g. as returned by BrOriginToScreenXYZO () 955. 
Result: br_scalar 


Corresponding z value in the camera actor’s co-ordinate space (view space). 


BrScreenxXYZToCamera () 


Description: | Convert point in screen space to point in a camera actor’s co-ordinate space (view 
space) (compare with BrPointToScreenXYZO () ,.,). 


Declaration: void BrScreenXYZToCamera (br_vector3* point, 
const br_actor* camera, const br_pixelmap* screen_buffer, 
br_int_16 x, br_int_16 y, br_scalar zs) 
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br_vector3 * point 


A non-NULL pointer to the vector to hold the converted point in camera space. 


const br_actor * camera 





A non-NULL pointer to the camera actor into whose co-ordinate space the point is 
to be converted. 


const br_pixelmap * screen_buffer 

A non-NULL pointer to the screen buffer to which the x & y co-ordinates apply. 
br_int_16 x 

X co-ordinate of pixel. 

br_int_16 y 

Y co-ordinate of pixel. 


br_ scalar zs 


Screen z co-ordinate. 
Between BrBegin(), & BrEnd() ,,. Between BrZbBegin(),, & BrZbEnd() ,). 
Computes the x & y co-ordinates in screen space, and together with the z co- 


ordinate applies the inverse projection transform, and stores the resulting vector at 
point. 


br_vector3 p; 

br_uint_32 depth; 

br_scalar sz; 

depth=BrPixelmapGet (&my_depth_buffer,x,y); 
sz=BrZbDepthToScreenZ (depth, &my_camera) ; 
BrScreenxYZToCamera(&p, &my_camera, &my_screen_buffer,x,y,s8z); 
BrOriginToScreenxYZO () ,;,, BrPointToScreenXYZO (),;,, 
BrMatrix4Perspective () 5,:. 
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The Rendering Engine 


Having described a 3D scene in terms of actors (models, lights, cameras, etc.) the next step is to 
produce a 2D image’. This is where BRender flexes its muscles and races through the actor hierarchy, 
accumulating transforms, computing lighting, and rendering faces. The process is performed in three 
phases: 


Phase 1 


e Traverse the actor hierarchy and produce a stream of models, materials, transforms, and rendering 
styles 


Phase 2 

e Discard back faces 

e Produce a stream of lit 2D face elements (typically triangles or quads) 
e Possibly perform binary space partitioning (for hidden surface removal) 


Phase 3 


e Possibly perform hidden surface removal (ordering, z-buffering, etc.) 
e Render faces to destination image (pixel map) 


Each phase produces data for the next phase to work on. It is possible in some implementations for a 
phase to commence before the previous phase has ended, possibly even processing in parallel. 


Depending upon the platform, BRender will exploit dedicated hardware wherever possible to 
perform some of the phases. 


In terms of how the process appears when using the BRender API, the following gives a simplified C 
skeleton of a possible application. 


BrBegin(); /* The BRender library is Initialised */ 
/* The application is initialised */ 
BrZbBegin();/* The rendering engine is initialised */ 


/* Set up a scene in terms of an actor hierarchy */ 


/* Elements in the scene are pre-processed by being added to the 
registry (models, materials, textures, shade tables) */ 


do/* Main loop */ 
{do /* Perform rendering of the scene from each camera */ 


{ 


/* Start supply of scene details to renderer */ 





* It is important to keep in mind that a rendering produces a 2D image on a pixel map — not necessarily the screen. 
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BrZbSceneRenderBegin (world, camera, colour_buffer,depth_buffer) ; 


for (...; ...; ...)/* Rendering one or more actor hierarchies */ 
{ 
/* Specify each branch of world hierarchy to include in 
rendering */ 


BrZbSceneRenderAdd(...); 


/* End supply of scene details to renderer */ 
BrZbSceneRenderEnd(); 


} Sons Cees) 
/* Update the scene */ 
} while (...); 
BrZbEnd();/* Close down the rendering engine */ 


BrEnd();/* Terminate the BRender library */ 


In order for the three rendering phases to take place the application must call BRender API functions 
to enable it to traverse an actor hierarchy. A ‘Begin’ function (BrzZzbSceneRenderBegin(),; in the 
example above) let’s BRender know that we’re about to supply it with a selection of actors in a 
specific hierarchy, that should be viewed from a certain camera actor within it, and the resulting 
image to be placed in a supplied pixel map, with a certain method used to remove hidden surfaces. 
Each actor in our selection to be included in the rendering is then supplied by using an ‘Add’ function 
(BrZbSceneRenderAdd (),, in the example). When all of the selection has been added an ‘End’ 
function is called (BrZbSceneRenderEnd(),, in the example). The output from the renderer is not 
defined until the ‘End’ function returns. Therefore you may make no assumptions about the contents 
of any output image buffers between the ‘Begin’ and ‘End’ functions, i.e. custom model and render 
bounds call-backs should not access the buffers. Furthermore, no assumption should be made 
regarding how the actor hierarchy is traversed during rendering, e.g. whether branch by branch or 
generation by generation. 


Initialising the Renderer 


Before rendering anything, the rendering engine must be initialised. This should be performed after 
library initialisation and before anything is added to the registry. Given that the registry is for 
performing pre-rendering preprocessing, it unsurprisingly needs to know beforehand which 
rendering engine is going to be used. 
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BrZbBegin () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


See Also: 


Initialise the Z-buffer renderer. This is a rendering engine which utilises a depth 
buffer (a pixel map matching the colour buffer) containing z values for each pixel, 
which can be used to determine whether another pixel at the same position should 
be drawn over the existing one. 


void BrZbBegin (br_uint_8 colour_type, br_uint_8 depth_type) 
br_uint_8 colour_type 

Pixel map type of buffer to render into. 

br_uint_8 depth_type 

Pixel map type of Z-buffer. 


Between BrBegin(),, & BrEnd() ,,. The registry is empty. No rendering engine 
is currently enabled. 


Checks that the specified colour and depth types can be supported, initialises 
registry for this renderer. 


BrZbEnd () ,,, BrZsBegin () 5. 


BrZsBegin () 


Description: 


Declaration: 


Arguments: 


Initialise the Z-sort renderer. This is a rendering engine which uses a bucket sort 
to determine the order in which primitives (faces, lines, points) should be rendered. 
void BrZsBegin (br_uint_8 colour_type, void* primitive, 
br_uint_32 size) 

br_uint_8 colour_type 

Pixel map type of buffer to render into. 

void * primitive 

Non-NULL pointer to an allocated block of memory to be used as a heap to hold 
rendered’ primitives and referenced vertices generated during rendering. 
br_uint_32 size 

Size of primitive heap. To ensure that everything is rendered completely, this 
should be large enough for the renderer to store the temporary data structures used 
to hold details of each rendered primitive and the transformed vertices indexed by 
them. A primitive can be anything from a point to a triangle (possibly a quad). For 
the purposes of estimation you should allow 26 bytes for each primitive and 64 
bytes for each unique vertex. The number of unique vertices can be calculated 





* i.e. not back faces 
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from the number of primitives, according to how vertices are shared by models’ 
faces. At best there will be an average of one vertex per face primitive (a 
tetrahedron - four faces, four vertices), at worst there will be an average of three 
vertices per face primitive (a scene of independent triangles)’. 


Note that clipping is likely to increase the number of vertices. 


If you estimate that there is an upper limit of about 1,000 faces (of front facing 
surfaces) in a rendering sequence with an average of 2.5 vertices per triangular face 
(including increases due to clipping) then the value of this member should be 
1,000(26+2.5x64), i.e. 186,000 bytes, call it 200KB. 


Preconditions: Between BrBegin(),, & BrEnd() ,,. The registry is empty. No rendering engine 
is currently enabled. 


Effects: | Checks that the specified colour types can be supported, initialises registry for this 
renderer. 


Remarks: — If size is insufficiently large, some primitives will be omitted from the rendering. 
In border line cases, these are likely to be faces of models toward the end of the 
traversal of the actor hierarchy (which may manifest itself as deterioration of models 
in a particular lineage). 


See Also: BrZsEnd(),,, BrZbBegin () ». 


Pre-Rendering Pre-Processing 


There are various optimisations that BRender can perform before rendering takes place. These apply 
to models, materials, textures and shade tables. The way that any of these are specified to BRender 
before rendering is by adding them to the registry. The registry can be thought of as a container for 
holding elements involved in a scene. It can also be used as a simple type of database, with fairly 
simple search facilities. The preprocessing takes place on each item as it is added to the registry, e.g. 
using BrModelAdd () 5... Any time an item is modified the preprocessing that BRender needs to be 
performed, will have to be redone. This is achieved by explicitly updating changed items using 
functions such as BrMaterialUpdate () ,,.. As one would hope, such updating only needs to be 
performed just before rendering takes place — rather than after each change. If no actor in a scene uses 
a registry item then that item doesn’t need to be updated. Conversely, if a actor uses a model, 
material, texture or shade table, that item must be in the registry and if changed must be updated 
before the actor is supplied to the renderer (even if indirectly). 


If an item is no longer involved in a scene, then it can be removed from the registry using a function 
such as BrTableRemove () 20. 


Functions to search the registry for a particular item or to enumerate over all items of a certain type 
can be found in the supplementary sections of structures br_model,,,, br_material,,,, and 
br_pixelmap,,,. 





* This may be higher if primitives are quads — consult your installation guide. 
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Hidden Surface Removal Schemes 


There are various schemes for rendering faces such that overlapping or intersecting faces are drawn 
correctly, i.e. nearer faces are in front of, and hide, farther faces. Each scheme is a different 
compromise between, quality, processing overhead, and memory overhead. 


The Z-Buffer 


The z buffer, or depth buffer, is a fast, high quality scheme, but uses a considerable amount of 
memory (something not likely to be found in abundance on games consoles). 


How the depth buffer works is platform dependent, but it generally consists of a memory buffer 
corresponding to the display buffer, with a depth value for each pixel. The values it contains typically 
represent distances from the front - zero would thus represent the position of the front clip plane. 
Each time a face is rendered, the z value of each pixel is converted into a depth value, and only if it 
has a nearer (lesser) z value than the one in the depth buffer will it be plotted (the depth value in the 
buffer is then updated). 


BRender supports 16 and 32 bit Z-Buffers, and a description of how the current implementation 
generally works now follows. 


The depth buffer contains unsigned values representing distance from the front clip plane. A view z 
ordinate of -hither_z (as specified in the camera) would correspond to a depth of zero. A view z 
ordinate of —-yon_z corresponds to a depth of Depth,,,,. which is an unsigned value of OxFFFFFFFF 
(in 32 bpp depth buffers, but OxFFFFO000 in 16 bpp). 


Note that as depth buffer values are treated by the rendering engine as unsigned words, before 
rendering the depth buffer should be filled to the maximum depth, i.e. OXFFFFFFFF. The following 
example call will suffice whatever the word size of the depth buffer: 

BrPixelmapFill (view->depth_buffer, OxFFFFFFFF) ; 


Thus when reading values from a depth buffer, the value will be in the range [0, Depth,,,.], with 
unwritten pixels having depth buffer values of whatever was used to Initialise them, e.g. 
OxXFFFFFFFF. 


The functions BrZbBegin () ,,, BreZbSceneRender () ,,, etc. are provided for applications requiring a 
Z-Buffer rendering engine. 


The following functions are provided to convert between depths, screen and view co-ordinates. 


BrZbDepthToScreenzZ () 


Description: | Convert z buffer depth [0,0xFFFFFFFF] to screen z [-32,768,+~32,767.9]. 


Declaration: br_scalar BrZbDepthToScreenZ (br_uint_32 depth_z, 
const br_camera* camera) 
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Arguments: br_uint_32 depth_z 
A 32 bit value read from the z buffer pixel map. 
const br_camera* camera 


Anon-NULL pointer to the camera being used for rendering, i.e. relevant to the 
depth values used in the z buffer. 


Result: br_scalar 
The corresponding screen z value. 


See Also: BrScreenZToCamera () ,,, BeScreenXYZToCamera () 5. 


BrZbScreenZToDepth () 


Description: | Convert screen z [-32,768,+~32,767.9] to z buffer depth [0,0xFFFFFFFF]. 


Declaration: br_uint_32 BrZbScreenZToDepth (br_scalar sz, const br_camera* 
camera) 


Arguments: br_scalar sz 


A screen z value as obtained from functions such as 
BrOriginToScreenXYZO () 556. 
const br_camera* camera 
Anon-NULL pointer to the camera being used for rendering, i.e. relevant to the 
depth values used in the z buffer. 
Result: br_uint_32 
A 32 bit depth value suitable for writing to a z buffer pixel map. 


See Also: BrScreenZToCamera () ,,, BrScreenXYZToCamera () »;. 


The Z-Sort 
See br_order_table,,,{ } 


The Z-Sort is a very fast, low quality scheme using relatively little memory (particularly for simple 
scenes). Before rendering, all primitives (faces or smaller elements, such as lines or points) are sorted 
according to the z value of one or more of their vertices. The primitives are then rendered farthest 
first. 


Clipping of intersecting faces involves a severe performance hit and is only likely to be implemented 
on very capable platforms. Checking for cyclic overlaps reduces performance still further. 


The particular method BRender uses to sort primitives is to use a bucket sort. This involves the use 
of one or more order tables. Each order table divides a stratum (depth range) of the observer’s z-axis 
into a number of equal sub-strata (depths). The model geometry of each model actor (using a 
particular order table) will be converted into rendering primitives, and each primitive will be added 
to the bucket (a linked list) corresponding to the sub-strata appropriate to its z-values. It is called a 
bucket sort because the order table may be considered as an ordered row of buckets into which items 
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are thrown (in any order) according to their value (one bucket per range of values). Thus the order in 
which primitives of the same sub-strata are drawn is undefined. 


Each order table effectively defines a separate layer of the rendered image, like an acetate. One 
should thus take care if order tables’ depth ranges overlap, to avoid far faces being drawn over near 
faces. This is only likely to be a problem for intersecting models in separate order tables. Order tables 
are drawn in order of sort_z (typically the nearest end of an order table). 


The application is responsible for ensuring model actors are using appropriate order tables. The 
rendering process can then traverse the actor hierarchy, processing each model into primitives and 
inserting these into the appropriate order tables. Actors can be assigned to order tables specifically, 
or by inheritance - there is a default, single bucket order table (spanning the entire view volume) 
which will be inherited if no ancestral actor defines one. Each new order table that is encountered 
during this process is inserted into an ordered linked list of order tables. When complete, the list of 
order tables is traversed, with the primitives rendered from each bucket in turn (from back to front). 


Performance is relatively independent of the number of buckets you have, given the use of a radix 
sort to determine into which bucket a primitive should be placed. Performance does decrease 
however, the more order tables you have. This is due to the overhead, as each new order table is 
encountered, required to insert the order table at the correct position in the linked list of order tables. 
This is only likely to be significant with a large number of order tables. 


It is difficult to give guidelines, as approaches to determining an appropriate set of order tables 
depends so much on the type of scene (sometimes, even from frame to frame, as models rotate and 
intersect). Approaches can vary from having a single order table with a large number of buckets, to a 
single bucket order table for each model. 


The functions BrZsBegin () ,,, BeZsSceneRender () ,;, etc. are provided for applications requiring a 
Z-Sort rendering engine. 


The following functions provide means of converting between z sort depth values (as required by 
order tables and supplied to primitive call-back functions). Note that the z sort depths are actually in 
a different range from view z values, i.e. depths are in the range [-hither_z,+yon_z] whereas view 
z values are in the range [-hither_z,-yon_z] (both ranges near to far). 


BrZsDepthToScreenzZ () 


Description: | Convert z sort depth [-hither_z,+tyon_z] to screen z [-32,768,+~32,767.9]. 


Declaration: br_scalar BrZsDepthToScreenZ(br_scalar depth_z, 
const br_camera* camera) 


Arguments: br_scalar depth_z 
A depth value read from an order table or obtained from a z sort primitive call-back. 
const br_camera* camera 


Anon-NULL pointer to the camera being used for rendering, i.e. relevant to the 
depth values used in primitives and order tables. 


Result: br scalar 


The corresponding screen z value. 
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See Also: BrScreenZToCamera () ,,, BcScreenXYZToCamera () 5. 


BrZsScreenZToDepth () 


Description: | Convert screen z [-32,768,+~32,767.9] to z sort depth [-hither_z,+tyon_z]. 


Declaration: br_scalar BrZsScreenZToDepth(br_scalar sz, const br_camera* 
camera) 


Arguments: br_scalar sz 


A screen z value as obtained from functions such as 
BrOriginToScreenXYZO () 556. 


const br_camera* camera 


Anon-NULL pointer to the camera being used for rendering, 1.e. relevant to the 
depth values used in primitives and order tables. 


Result: br scalar 


A depth value suitable for writing to an order table or comparing with values of z 
obtained from a z sort primitive call-back. 


See Also: BrScreenZToCamera () ,,, BrScreenXYZToCamera () »;. 


Other Schemes 


Other hidden surface removal schemes exist and sometimes are a result of the rendering method 
used. These include: 

Binary Space Partitioning 

Voxels 

Ray Tracing 

Scan Line Rendering 


Rendering Functions 


There are two ways of rendering a scene. Either the scene is defined in a single hierarchy and 
rendered as a whole, or a scene is defined in terms of a selection of subtrees of a single hierarchy. In 
the former case, only one function needs to be called, Br[Zb|Zs]SceneRender () ;,,;, this effectively 
wraps up the three functions required for the latter case, Br[Zb|Zs]SceneRenderBegin () 3536, 
Br[Zb|Zs|SceneRenderAdd () 377, and Br[ZblZs]SceneRenderEnd () 49); Note that in both cases, 
the camera must be a descendant of the scene root actor, as should all the sub-trees. Ifan environment 
actor is currently specified then it must also be a descendant of the scene root. 


Note that there are two key call-back functions that can get called during rendering. These are a 
custom model rendering call-back (see br_renderbounds_cbfn,,,) and a render bounds call-back 
(see br_model_custom_cbfn,,,). The custom model rendering call-back is specified within the 
br_model,,, structure defined for a model actor and enables an application to make a model’s 
rendering dependent upon information only available at the time it’s processed by the renderer. For 
similar reasons, the render bounds call-back is called for every model that affects the output image, 


Copyright © 1996 Argonaut Technologies Limited 3 3 


Scene Rendering 


allowing the application to take note of information only available at the time the model’s are 
processed by the renderer. The trivial use of the render bounds call-back is to keep track of modified 
rectangles of the output image. The render bounds call-back is specified before rendering 
commences, using Br[Zb|Zs]RenderBoundsCallbackSet () 39j39. 


There is also a special call-back, br_primitive_cbfn,,;, only used in the Z-Sort renderer. This 
allows customised insertion of primitives into order tables. 


BrZbSceneRender () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


Remarks: 


See Also: 


All-in-one function to render a scene using the Z-Buffer renderer. 


void BrZbSceneRender (br_actor* world, br_actor* camera, 
br_pixelmap* colour_buffer, br_pixelmap* depth_buffer) 


br_actor * world 

Anon-NULL pointer to the root actor of a scene. 

br_actor * camera 

Anon-NULL pointer to a camera actor that is a descendant of the root actor. 


br_pixelmap * colour_buffer 





Anon-NULL pointer to the pixel map to render the scene into, whose type is 
colour_type as supplied to BrZbBegin () »s. 


br_pixelmap * depth_buffer 


Anon-NULL pointer to the pixel map to be used as a depth buffer whose type is 
depth_type as supplied to BrZbBegin () »s. It must have the same width and 
height as the colour buffer. See BrPixelmapMat ch () »».. 


Between BrBegin(),, & BrEnd(),,. Between BrZbBegin(),, & BrZbEnd () ,). 
Not currently rendering. 


Equivalent to a call of 

BrZbSceneRenderBegin (world, camera, colour_buffer,depth_buff 
er),; followed by BrzbSceneRenderAdd (world), and 
BrZbSceneRenderEnd () ;.. 


The colour buffer and depth buffer should not be texture maps (or even shade 
tables), though they can of course be subsequently added as such once the 
rendering has completed. 


BrZbRenderBoundsCallbackSet () », BrZbModelRender (),,;. 


BrZsSceneRender () 


Description: 


Declaration: 
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All-in-one function to render a scene using the Z-Sort renderer. 


void BrZsSceneRender (br_actor* world, br_actor* camera, 
br_pixelmap* colour_buffer) 
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Arguments: 


Preconditions: 


Effects: 


Remarks: 


See Also: 
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br_actor * world 
Anon-NULL pointer to the root actor of a scene. 
br_actor * camera 


Anon-NULL pointer to a camera actor that is a descendant of the root actor. 


br_pixelmap * colour_buffer 





Anon-NULL pointer to the pixel map to render the scene into, whose type is 
colour_type as supplied to BrZsBegin () ».. 

Between BrBegin(),, & BrEnd() ,,. Between BrZsBegin(),, & BrZsEnd () 4). 
Not currently rendering. 

Equivalent to a call of 

BrZsSceneRenderBegin (world, camera, colour_buffer),, followed by 
BrZsSceneRenderAdd (world), and BrZsSceneRenderEnd () 5. 


The colour buffer should not be a texture map (or even a shade table), though it can 
of course be subsequently added as such once the rendering has completed. 


BrZsRenderBoundsCallbackSet () ;, BrZsModelRender () 5;,, 
BrZsPrimitiveCallbackSet () 4. 


BrZbSceneRenderBegin () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


Set up a new scene to be rendered using the Z-Buffer renderer, processing the 
camera, lights and environment. 


void BrZbSceneRenderBegin (br_actor* world, br_actor* camera, 
br_pixelmap* colour_buffer, br_pixelmap* depth_buffer) 


br_actor * world 

Anon-NULL pointer to the root actor of a scene. 

br_actor * camera 

Anon-NULL pointer to a camera actor that is a descendant of the root actor. 


br_pixelmap * colour_buffer 





Anon-NULL pointer to the pixel map to render the scene into, whose type is 
colour_type as supplied to BrZbBegin () ».. 


br_pixelmap * depth_buffer 
Anon-NULL pointer to the pixel map to be used as a depth buffer whose type is 


depth_type as supplied to BrZbBegin () ,,. It must have the same width and 
height as the colour buffer. See BrPixelmapMatch () ,... 


Between BrBegin() , & BrEnd() ,,. Between BrZbBegin(),, & BrZbEnd () ,). 
Not currently rendering. 


Enter rendering state, prepare for destination buffers, preprocess view, screen and 
environment transforms, preprocess enabled lights, handle environment actor, 
preprocess enabled clip planes. 
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Remarks: 


See Also: 


The colour buffer and depth buffer should not be texture maps (or even shade 
tables), though they can of course be subsequently added as such once the 
rendering has completed. 


BrZbSceneRenderAdd () ,,, BrZbSceneRenderEnd () 33, 
BrZbRenderBoundsCallbackSet () », BrZbModelRender (),,;. 


BrZsSceneRenderBegin () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


Remarks: 


See Also: 


Set up a new scene to be rendered using the Z-Sort renderer, processing the 
camera, lights and environment. 


void BrZsSceneRenderBegin (br_actor* world, br_actor* camera, 
br_pixelmap* colour_buffer) 


br_actor * world 

Anon-NULL pointer to the root actor of a scene. 

br_actor * camera 

Anon-NULL pointer to a camera actor that is a descendant of the root actor. 


br_pixelmap * colour_buffer 





Anon-NULL pointer to the pixel map to render the scene into, whose type is 
colour_type as supplied to BrZsBegin () ».. 


Between BrBegin(),, & BrEnd() ,,. Between BrZsBegin().,, & BrZsEnd () 4). 
Not currently rendering. 


Enter rendering state, prepare for destination buffer, preprocess view, screen and 
environment transforms, preprocess enabled lights, handle environment actor, 
preprocess enabled clip planes. 


The colour buffer should not be a texture map (or even a shade table), though it can 
of course be subsequently added as such once the rendering has completed. 
BrZsSceneRenderAdd () ,,, BrZsSceneRenderEnd () 33, 


BrZsRenderBoundsCallbackSet () ,, BrZsPrimitiveCallbackSet () 4, 
BrZsModelRender () 5;,. 


BrZbSceneRenderAdd () 


Description: 
Declaration: 


Arguments: 


Preconditions: 
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Include an actor (and its descendants) of the world inthe current rendering. 
void BrZbSceneRenderAdd (br_actor* tree) 

br_actor * tree 

Anon-NULL pointer to an actor hierarchy, which must be a descendant of the 
world hierarchy supplied to BrZbSceneRenderBegin () ,;. 


Between BrBegin(),, & BrEnd() ,,. Between BrZbBegin(),, & BrZbEnd () ,. 
Currently rendering, i.e. between BrZbSceneRenderBegin (),; and 
BrZbSceneRenderEnd () ,,. Not within a custom model render call-back or render 
bounds call-back 
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Remarks: 


See Also: 
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Add actor to list of actors to be rendered. 


Whether rendering takes place during this function or sometime before the return 
of BrZbSceneRenderEnd () ,. is undefined. When custom model render and 
render bounds call-back functions are called is similarly undefined. 


BrZbSceneRenderBegin () ;;, BrZbSceneRenderEnd () ;:, 
BrZbRenderBoundsCallbackSet () ,,, BreZbModelRender () ,;;. 


BrZsSceneRenderAdd () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 


Remarks: 


See Also: 


Include an actor (and its descendants) of the world inthe current rendering. 
void BrZsSceneRenderAdd (br_actor* tree) 
br_actor * tree 


Anon-NULL pointer to an actor hierarchy, which must be a descendant of the 
world hierarchy supplied to BrZ2sSceneRenderBegin () ,. 


Between BrBegin(),, & BrEnd() ,,. Between BrZsBegin(),, & BrZsEnd () 4). 
Currently rendering, i.e. between BrZsSceneRenderBegin () , and 
BrZsSceneRenderEnd () ;s. Not within a custom model render call-back, render 
bounds call-back or primitive call-back. 


Add actor to list of actors to be rendered. 


Whether rendering takes place during this function or sometime before the return 
of BrZsSceneRenderEnd (),, is undefined. When custom model render, render 
bounds and primitive call-back functions are called is similarly undefined. 


BrZsSceneRenderBegin () ,, BrZsSceneRenderEnd () ;:, 
BrZsRenderBoundsCallbackSet () ,», BrZsPrimitiveCallbackSet () x, 
BrZsModelRender () 55. 


BrZbSceneRenderEnd () 


Description: 
Declaration: 


Preconditions: 


Effects: 


Remarks: 


See Also: 
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Complete the specification of actors to be rendered ina scene, and their rendering. 
void BrZbSceneRenderEnd (void) 


Between BrBegin() ,, & BrEnd() ,,. Between BrZbBegin(),, & BrZbEnd () ,). 
Currently rendering, i.e. after BreZbSceneRenderBegin () ,;. Not within a custom 
model render call-back or render bounds call-back 


By the time this function ends, the scene as specified in terms of world root, camera 
and sub-trees, will have been rendered to the output buffers. 

Whether rendering takes place during this function or sometime before the return 
of BrZbSceneRenderEnd (),, is undefined. When custom model render and 
render bounds call-back functions are called is similarly undefined. 
BrZbSceneRenderBegin () ,,, BreZbSceneRenderAdd () ,,, 
BrZbRenderBoundsCallbackSet () ,,, BreZbModelRender () ,;;. 
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BrZsSceneRenderEnd () 


Description: 
Declaration: 


Preconditions: 


Effects: 


Remarks: 


See Also: 


Complete the specification of actors to be rendered ina scene, and their rendering. 
void BrZsSceneRenderEnd (void) 


Between BrBegin() , & BrEnd() ,,. Between BrZsBegin (),, & BrZsEnd () ,). 
Currently rendering, i.e. after BreZsSceneRenderBegin () ,,, Not within a custom 
model render call-back, render bounds call-back, or primitive call-back. 


By the time this function ends, the scene as specified in terms of world root, camera 
and sub-trees, will have been rendered to the output buffer. 


Whether rendering takes place during this function or sometime before the return 
of BrZsSceneRenderEnd(),, is undefined. When custom model render, render 
bounds, and primitive call-back functions are called is similarly undefined. 


BrZsSceneRenderBegin () ,, BrZsSceneRenderAdd () ,,, 
BrZsRenderBoundsCallbackSet () ,, BrZsPrimitiveCallbackSet () 4, 
BrZsModelRender () 55,. 


BrZbRenderBoundsCallbackSet () 


Description: 


Declaration: 


Arguments: 


Preconditions: 
Effects: 


Result: 


Remarks: 


See Also: 
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Set the call-back function invoked for each rendered actor. For example, a call-back 
can be set up to log those rectangles in the colour buffer that have been written to 
(dirty rectangle flagging). 


br_renderbounds_cbfn* 


BrZbRenderBoundsCallbackSet (br_renderbounds_cbfn* new_cbfn) 
br_renderbounds_cbfn * new_cbfn 


A pointer to the new call-back function. Specify the old call-back function when a 
function call-back is not required. 


Between BrBegin(),, & BrEnd(),,. Between BrZbBegin(),, & BrZbEnd () ,. 
Not currently rendering. 


Defines a function that will be called during rendering for each model that affects 
the output buffers. 


br_renderbounds_cbfn * 
Returns a pointer to the old call-back function. 


Exactly when the call-back function gets called is undefined except that it will be 
sometime between BrZbSceneRenderBegin(),; and 

BrZbSceneRenderEnd () ,;. It is also not necessarily associated with a particular 
point in the rendering process. 


br_renderbounds_cbfn,,,,br_model_custom_cbfn,,,. 
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BrZsRenderBoundsCallbackSet () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


Result: 


Remarks: 


See Also: 


Set the call-back function invoked for each rendered actor. For example, a call-back 
can be set up to log those rectangles in the colour buffer that have been written to 
(dirty rectangle flagging). 


br_renderbounds_cbfn* 


BrZsRenderBoundsCallbackSet (br_renderbounds_cbfn* new_cbfn) 


br_renderbounds_cbfn * new_cbfn 


A pointer to the new call-back function. Specify the old call-back function when a 
function call-back is not required. 


Between BrBegin(),, & BrEnd() ,,. Between BrZsBegin(),, & BrZsEnd () 4). 
Not currently rendering. 


Defines a function that will be called during rendering for each model that affects 
the output buffer. 


br_renderbounds_cbfn * 

Returns a pointer to the old call-back function. 

The actor order table will be supplied to the call-back function. 

Exactly when the call-back function gets called is undefined except that it will be 
sometime between BrZsSceneRenderBegin(),, and 


BrZsSceneRenderEnd () ;;. [t is also not necessarily associated with a particular 
point in the rendering process. 


br_renderbounds_cbfn,,,, br_model_custom_cbfn,,). 


BrZsPrimitiveCallbackSet () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


Result: 
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Set the call-back function invoked for each primitive generated by the Z-Sort 
renderer. This call-back can be used to perform customised insertion of primitives 
into order tables. 


br_primitive_cbfn* 
BrZsPrimitiveCallbackSet (br_primitive_cbfn* new_cbfn) 


br_renderbounds_cbfn * new_cbfn 


A pointer to the new call-back function. Specify the old call-back function when a 
function call-back is not required. NULL will indicate that the default call-back 
function should be used. 


Between BrBegin() , & BrEnd() ,,. Between BrZsBegin(),, & BrZsEnd () ,). 
Not currently rendering. 


Defines a function that will be called during rendering for each front facing 
primitive that is to be inserted into the order table. 


br_renderbounds_cbfn * 


Returns a pointer to the old call-back function. 
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Remarks: 


See Also: 


Exactly when the call-back function gets called is undefined except that it will be 
sometime between BrZsSceneRenderBegin (),, and 

BrZsSceneRenderEnd () ;;. However, it may be assumed that rendering to the 
output buffer has not yet commenced. 


br_primitive_cbfn,,,,br_model_custom_cbfn,;. 





‘Terminating the Renderer 


Once rendering has completed, all items in the registry should be removed (not necessarily freed) and 
the rendering engine closed down. This should also happen before using a different rendering engine 
or rendering to a different type of pixel map or image, e.g. rendering to an 8 bit pixel map when the 
current rendering is to a 24 bit video buffer. 


BrZbEnd () 


Description: 
Declaration: 


Preconditions: 


Effects: 
See Also: 


Close down the Z-Buffer renderer. 
void BrZbEnd (void) 


Between BrBegin(),, & BrEnd() ,,. BrZbBegin(),, has been called, and 
BrZbEnd(),, has not yet been called since. The registry is empty. No other 
rendering engine is currently enabled. 


Releases resources used by the Z-Buffer renderer. 


BrZbBegin () », 


BrZsEnd () 


Description: 
Declaration: 


Preconditions: 


Effects: 
See Also: 
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Close down the Z-Sort renderer. 
void BrZsEnd (void) 


Between BrBegin(),, & BrEnd() ,,. BrZsBegin(),, has been called, and 
BrZsEnd(),, has not yet been called since. The registry is empty. No other 
rendering engine is currently enabled. 


Releases resources used by the Z-Sort renderer. 


BrZsBegin () >. 
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Image Support 


Pixel Maps 
See br_pixelmap,,, 


In BRender, all two dimensional images are described in terms of pixel maps. A pixel map may 
represent any device that can be described in terms of width and height, and can support primitive 
graphical operations such as plot a point, line or triangle, e.g. video memory, a printer, or an area of 
memory. As far as BRender is concerned there is very little difference between them, it’ll quite 
happily produce an image on a dot matrix printer as on an accelerated graphics card. Of course, the 
performance may be quite different depending on what device the pixel map refers to. On some 
platforms there may be graphic acceleration hardware which may only be usable on video memory, 
which may be inaccessible to BRender, thus rendering toa screen pixel map may be a few times faster 
than rendering to a pixel map based in main memory. Sometimes it’s the other way around. 


Using Pixel Maps 


In general, you’ll use a pixel map for the following: 

The output image 

A depth buffer (if you’re using the Z-Buffer renderer) 

An off-screen image (if you’re using double buffering) 

Any sub-images copied to the output image 

Any images to be involved in the scene on the surface of models 
‘Texture maps for models’ surfaces 

Shade tables for indexed texture maps 


Operations 


The operations available on pixel maps include: 

e setting points, lines, and rectangles to specific colours 
© copying rectangles from one pixel map to another 

¢ writing text 


Rendering To Pixel Maps 


BrPixelmapDirtyRectangleFill(),, and BrPixelmapDirtyRectangleCopy (),, are useful 
when using results from within a render bounds call back function (see 
br_renderbounds_cbfn,,,). 


In some cases a scene rendering may only affect a few small areas of the destination pixel map. It can 
provide some performance improvement if only these areas are cleared each frame, rather than 
clearing the entire pixel map. The procedure is to utilise the br_renderbounds_cbfn,,, call-back, 
setting it before rendering (using BrZbRenderBoundsCallbackSet () ,.), collect a list (or overall 
bounding rectangle) of bounds supplied, and use this to clear the destination pixel map just before 
the next rendering. Each rectangle can be cleared or reset using 
BrPixelmapDirtyRectangleFill(),, or BrPixelmapDirtyRectangleCopy (),;. These 
functions are used because they can be faster, though they may utilise a larger rectangle than that 
specified (for more efficient word aligned operation). 
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BrPixelmapDirtyRectangleFill () 


Description: 


Declaration: 


Arguments: 


Effects: 


Remarks: 


Example: 


See Also: 


Set an area of a pixel map that covers a specified rectangle to a given value. 

This function is intended to be used in conjunction with a rendering call-back to 

reset those regions of a pixel map that have been rendered to. 

void BrPixelmapDirtyRectangleFill(br_pixelmap* dst,br_int_16 
x, br_int_16 y, br_uint_16 w, 

br_uint_16 h,br_uint_32 colour) 

br_pixelmap * dst 

A pointer to the destination pixel map. 

br_int_16 x,y 

Co-ordinates of the rectangle’s top left corner. 

br_uint_16 w,h 

Rectangle width and height (in pixels). 


br_uint_32 colour 


Value to set each pixel to. 

Sets an area of pixels in the destination pixel map to a value, such that each pixel 
in the specified rectangle is reset. 

The actual area affected depends upon the platform and implementation, but this 
function is intended to provide the fastest way of resetting a particular rectangle. It 
is possible that this could be as large as the entire pixel map. Hopefully, most 
redundant, repeated calls would be ignored. 


br_uint_32 afar=Oxfffrrret ; 
br_int_16 drx, dry; 
br_uint_16 drw, drh; 


br_pixelmap* zbuffer; 


BrPixelmapDirtyRectangleFill (zbuffer,drx,dry,drw,drh, zfar) ; 
BrZbRenderBoundsCallbackSet () ;, 


BrPixelmapDirtyRectangleCopy () 


Description: 


Declaration: 


42 


Copy a rectangular window of data from one pixel map to the same position in 
another pixel map. 


This function is intended to be used in conjunction with a rendering call-back to 
copy those regions of a pixel map that have been rendered to. 


void BrPixelmapDirtyRectangleCopy (br_pixelmap* dst,const br_ 
pixelmap* src, br_int_16 x, br_int_16 y,br_uint_16 w, 
br_uint_16 h) 
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Arguments: br_pixelmap * dst 


A pointer to the destination pixel map. 


const br_pixelmap * src 
A pointer to the source pixel map. 
br_int_16 x,y 
Co-ordinates of the rectangle’s top left corner. 
br_uint_16 w,h 
Rectangle width and height (in pixels). 
Preconditions: | The source and destination pixel maps must have the same type and dimensions. 


Effects: | Copies anarea of pixels from the source to the destination pixel map, such that each 
pixel in the specified rectangle is copied. 

Remarks: The actual area copied depends upon the platform and implementation, but this 
function is intended to provide the fastest way of copying a particular rectangle. It 
is possible that this could be as large as the entire pixel map. Hopefully, most 
redundant, repeated calls would be ignored. 

Example: 
br_int_16 drx, dry; 
br_uint_16 drw, drh; 
br_pixelmap* offscreen; 


br_pixelmap* backdrop; 


BrPixelmapDirtyRectangleCopy (offscreen, 
backdrop, drx,dry,drw,drh) ; 


See Also: BrZbRenderBoundsCallbackSet () 


Pixel Maps To Video 


There are three ways of rendering to video: 

1. Render direct to a pixel map representing a video device 

2. Render to a memory based pixel map and copy it to a video pixel map each frame 

3. Render toa memory based pixel map and swap it with a video pixel map each frame 


All three methods suffer from problems of tearing, the first also from visible image construction. That 
is, if modifications to video memory are not postponed until the start of the CRT fly-back. 


Fortunately, BRender provides a function BrPixelmapDoubleBuf fer (),, which should be used to 
avoid the possible problems as described above. This will perform, transparently, either of the last 
two methods. If the video device supports page swapping then it will utilise that feature, otherwise 
it will copy a pixel map to video memory. However, it will automatically do this at the start of the 
CRT fly-back, wherever possible. 
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BrPixelmapDoubleBuffer () 


Description: _ If the destination pixel map relates to a device, for example a graphics hardware 
screen, then the source ‘off-screen’ pixel map is copied to the destination pixel map 
at a suitable moment. If the source is an off screen pixel map (created using 
BrPixelmapMatch (..., BR_PMMATCH_OFF SCREEN) ,,) then it is swapped with 
the destination pixel map instead. 














Otherwise, the function is equivalent to BrPixelmapCopy ().,; and the source 
pixel map is copied to the destination pixel map. 


Declaration: void BrPixelmapDoubleBuffer (br_pixelmap* dst, 
br_pixelmap* src) 


Arguments: br_pixelmap * dst 
A pointer to the destination pixel map. 
br_pixelmap * src 
A pointer to the source pixel map. 


Effects: If the destination is a device that supports a ‘wait for vertical retrace’ function, a 
copy or swap will be performed pending that event. 


If the destination is a device that supports double buffering and the source pixel 
map is an off-screen secondary buffer, the destination and source will be switched 
to use each other’s buffers. 


Remarks: — Returns immediately, but will cause further rendering or calls of this function to 
block until the copy or swap has been completed. 


Pick Functions 


A common function required of a 3D API, by developers working ona 3D user interface, is one that 
will return the model at a particular pixel. This is typically used for picking functions, e.g. mouse 
selection operations by the user. For this purpose, BRender provides the function 
BrScenePick2D(),, which will invoke a specified call-back function for each model actor whose 
bounds contain the pixel. It is up to the application to determine greater precision, such as which 
model, faces or texture co-ordinates appear at the pixel. 


There is also a 3D version of the pick function, called BrScenePick3D (),,. This will perform a 
similar operation, but operates on a bounding box rather than a screen pixel. However, if the image 
is depth buffered, the depth information for a pixel could be used in conjunction with 
BrActorToScreenMatrix4 (),, to produce a bounding box, more closely corresponding to the pixel 
resulting from a model’s face. 
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Maths 


One of the essential aspects of any 3D graphics API is a good set of maths data types and functions. 


Fractional representation is almost unavoidable when transforming 3D scenes into 2D co-ordinates, 
but there is usually a performance penalty associated when using floating point types, so BRender 
also provides a fixed point representation. This is in the form of an alternate library. The same types 
are used, so the switch between fixed and floating point is performed at compile time. Naturally there 
are range and precision considerations, but at least you have the choice. In fact, on some platforms 
with dedicated hardware, the floating point library is faster than the fixed point one. 


3D scenes in terms of models, positions and transformations, are conventionally described in terms 
of Cartesian co-ordinates, vectors, and matrices. BRender provides data types and structures to cater 
for this, and goes even further, providing a dedicated angle type, the Euler Angle Set, for simpler 
rotation transforms, and the Unit Quaternion for sophisticated rotational transforms. 


C Types 


Various BRender data structures and functions still make occasional use of basic C types such as int 
and unsigned. However, such use tends to be for simple integer quantities and flags. The floating 
point types are rarely used except of course for arguments and results of conversion functions. 


Fundamental ‘Types 


BRender defines a selection of sized signed and unsigned integer types, for uses where a specific 
word size is critical (see br_int_8/16/32,,,and br_uint_8/16/32,,,). 


BRender defines a selection of fixed point types for later use by application oriented types (see 
br_fixed_[1s] [su] [f],,,). 


Angles 


Although a scalar type could suffice for an angle, it tends to end up representing rotations given that 
a scalar is not necessarily restricted to a range corresponding to a single rotation. For the purpose of 
strictly representing an angle (as opposed to a rotation), the br_angle,,; type is provided. By its 
nature, this type can only represent angles, readily appreciated given that it is a two byte type, with 
65536 corresponding to 360°, i.e. 0°. 


Scalars 


When it comes to representing numbers in general, particularly co-ordinates, a number is needed that 
can take on a wide range of values. A floating point number is ideal, but as not all platforms can deal 
with these (quickly or at all), BRender’s general value type is library dependant. Using one library 
br_scalar,, compiles to a float, using the other it compiles to a fixed point representation 
(br_fixed_l1s,,,). 
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Fractions 


Where storage is critical and values are always less than unity in magnitude, it makes sense to only 
store the fractional components of values. For this reason BRender defines signed and unsigned 
fraction types (see br_fraction,,, and br_ufraction,,,). These are not generally expected to be 
used by the application, but may come in handy when large numbers of fraction based data structures 
are required. 


Vectors 
See br_vector2,,,, br_vector3,,, br_vector4,,,. 


The vector plays a central part in 3D geometry and BRender implements 2, 3 and 4 element vectors 
to enable efficient representations. 2D vectors can be implemented either using 2 element vectors 
(any homogenous element being implicit), or as 3 element vectors, with an explicit homogenous 
element. 3D vectors can be implemented either using 3 element vectors (any homogenous element 
being implicit), or as 4 element vectors, with an explicit homogenous element. 


Matrices 
See br_matrix23,,, br_matrix34,,,, br_matrix4,,,. 


With 2D texture and 3D geometry transformations being crucial to 3D rendering, BRender 
implements various matrix data structures and arithmetic functions. br_matrix23,,, is effectively a 
2D 3x3 transformation matrix (for use with homogenous 2D co-ordinates) with an implicit third 
column. Similarly, br_matrix34,,, is effectively a 3D 4x4 transformation matrix (for use with 
homogenous 3D co-ordinates) with an implicit fourth column. br_matrix4,, is a fully defined 3D 
4x4 transformation matrix (for use with homogenous 3D co-ordinates). 


Note that BRender applies a matrix to a vector by pre-multiplying the matrix by the vector. 
Furthermore, a matrix A is multiplied by matrix B (written AB) by computing the dot product of 
each row of A with each column of B for each element. Further still, ABC is understood to mean 
(AB)C (equivalent to A(BC)). Post-Multiply M by A means MA, and Pre-Multiply M by A 
means AM. 


Euler Angle Sets 
See br_euler,,,. 


The Euler’ Angle Set is a set of three angles and an ordering that represents a rotational 
transformation about each of the orthogonal axes. It is an easier and simpler way of specifying such 
transforms, rather than composing them out of rotational matrices. 


Unit Quaternions 
See br_quat,,,. 


The quaternions form an extension to the real numbers that can be used to represent rotations. Just 
as we form the complex numbers by starting with the real numbers and including an extra number i 





* Pronounced “Oiler” as in “Boiler”. 
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with the property i*=-1, the quaternions are formed by adding in three extra numbers: i, j, and k, with 


1°=j’=k’=-1. In addition these new numbers obey the following rules: 


ij = k = -ji 
jk =i = -kj 
ki = j = -ik 


For example: 





(1+i1)(2-2k) = 2+ 2i1-2k-2ik = 2+ 21+ 2j-2k 


Just as with complex numbers, the modulus of a quaternion is defined by: 


: A 2 2 2 2 
lw+xityj+zk| = Jwot+x +y +z 


The quaternions with unit modulus are known as the unit quaternions. 
The inverse of a unit quaternion® q=w+xi+yj+zk, is q'=w-xi-yj-zk. So we have qq'=q'‘q=1. 


Rotations may be represented as unit quaternions as follows. Suppose we wish to rotate through an 
angle @ around the axis defined by the unit vector (n,,n,,n,). The corresponding quaternion q is given 


by: 
q = c0s30+(n,i+n,j +n_k)sin50 


The value of quaternions lies in the fact that if we multiply the quaternions for two rotations together 
then the resulting quaternion represents the resulting rotation. These operations are considerably 
simpler than those needed to represent rotations using matrices. 


More explicitly, given a vector (V,,V,,V,), We apply the rotation via the quaternion q representing it 
using the following formula: 


Vidtvijtvk = g(vitvyj+ v.K)q- 


There is a further property of quaternions requiring a little more discussion. A rotation through 360° 
is effectively the same as no rotation. However, if we substitute 0° and 360° into the earlier formula 
for q above, we find that these rotations are represented by +1 and -1 respectively. This means that 
both +1 and -1 represent the identity transform. This is not a problem though, it simply means that 
every rotation can be represented by two different quaternions. If we use the above formula for 
applying a quaternion to a vector, then whichever of the two equivalent quaternions we choose, we 
will still obtain the same result. 


* The inverse of a non-unit quaternion q is (w-xi-yj-zk)/Iql’. 
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Resource Management 


BRender divides all memory allocation according to a set of classes, called memory classes, or 
resource classes. Each memory class is notionally separate and is useful in distinguishing between 
different types of memory usage (for allocation policies, debugging, performance analysis, releasing 
all memory in a class as a whole). The term resource class is used to indicate an advanced use of the 
memory class, ina structured fashion, where resource blocks (special blocks of memory allocated from 
the resource class) can be allocated as dependants of another resource block. Similar to C++, this 
enables destruction of a resource block to automatically delete all its dependent resource blocks 
automatically. This lightens the application programmer’s burden of responsibility. BRender utilises 
this feature in a lot of the data structures it allocates —-br_actor,, is a good example in the way it 
may allocate default, type specific data. 


Generally, you will not need to explicitly free resource blocks allocated by BRender, even if you 
overwrite pointers to them, as a separate record is maintained of their existence and what they are 
attached to. This ensures that when something is freed that any resource blocks attached to it are also 
freed. The only time attached resources need to be freed sooner is if memory is very limited and there 
is a disproportionately high turnover of allocations of a dependant compared to its parent’s lifetime. 
In such cases BrResFree () ;, can be used (with caution) to free the dependent immediately, e.g. 
destroying unwanted models loaded using BrFmtASCLoad () 5s. 


For simple applications the simple memory allocation functions can be used (see 

BrMemAllocate () ;,), and where structured allocation is required, resource blocks can be allocated 
from the BR_MEMORY_APPLICATION resource class. For more advanced applications requiring 
greater control, new resource classes can be created (see br_resource_class;;,). 





There are other features of resource blocks, including the ability to have a call-back function called 
for each resource block of a particular class. 


You will find BrResStrDup () 5) quite useful for specifying identifiers of various data structures. 


BrResAllocate () 


Description: — Allocate a new resource block of a given class. 


Declaration: void* BrResAllocate(void* vparent, br_size_t size, 
int res_class) 


Arguments: void * vparent 
A pointer to a parental resource block, or NULL if it will have no parent. 
br_size_t size 
Size of block in bytes. 
int res_class 
Resource class (See Memory Management, page 54). 
Result: void * 


Returns a pointer to the allocated resource block (of at least size bytes). 
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BrResAdd () 


Description: 
Declaration: 


Arguments: 


Result: 


Remarks: 


Add a resource block as a dependant or child of another. 
void* BrResAdd(void* vparent, void* vres) 
void * vparent 

Anon-NULL pointer to the parent resource block. 


void * vres 





Anon-NULL pointer to the child resource block (will be removed from any current 
parent). 


void * 
Returns a pointer to the child resource block. 


Once a resource block has been added as a dependant, it can be freed due to its 
parent being freed. 


BrResStrDup () 


Description: 
Declaration: 


Arguments: 


Effects: 


Result: 


Remarks: 


Duplicate a string. 

char* BrResStrDup(void* vparent, const char* str) 
void * vparent 

A pointer to a parental resource block (or NULL if independent). 
const char * str 

Anon-NULL pointer to the source string. 


Allocates a resource block (from the BR_-MEMORY_STRING resource class) and 
copies a string into it. 





char * 
Returns a pointer to the allocated resource block. 


This is most useful for specifying identifiers for various BRender data structures. 


BrResClass () 


Description: 
Declaration: 


Arguments: 


Result: 
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Determine the class of a given resource block. 
br_uint_8 BrResClass(void* vres) 
void * vres 

Anon-NULL pointer to a resource block. 
br_uint_8 


Returns the resource class. 
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BrResSize () 


Description: 


Declaration: 


Arguments: 


Result: 


Determine the size of a given resource block. 
br_uint_32 BrResSize(void* vres) 
void * vres 

Anon-NULL pointer to a resource block. 
br_uint_32 


Returns the size of the resource block in bytes (may not necessarily be the same as 
that specified upon allocation, but will not be less). 


BrResChildEnum () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


Remarks: 


Example: 
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Enumerate through all dependant resource blocks of a particular resource block. 


br_uint_32 BrResChildEnum(void* vres, 
br_resenum_cbfn* callback, void* arg) 


void * vres 
Anon-NULL pointer to a resource block. 


br_resenum_cbfn * callback 





Anon-NULL pointer to a call-back function. 
void * arg 
An optional argument to pass to the call-back function. 


Invoke a call-back function for each child of a resource block. The call-back 1s 
passed a pointer to each child, and its second argument is an optional pointer (arg) 
supplied by the user. The call-back itself returns a br_uint_32,,, value. The 
enumeration will halt at any stage if the return value is non-zero. 


br_uint_32 


Returns the first non-zero call-back return value, or zero if all children are 
enumerated. 


This function does not recurse throughout all descendants. If you require such 
behaviour, you’ll need to implement it yourself. 


br_uint_32 example_callback(void *vres, void *arg) 
{br_uint_32 value; 


return(value) ; 


{ br_uint_32 ev; 
void *rblock; 


ev = BrResChildEnum(rblock, &example_callback,NULL) ; 
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BrResRemove () 


Description: | Remove a resource block from a parent. 
Declaration: void* BrResRemove (void* vres) 
Arguments: void * vres 
Anon-NULL pointer to the resource block to be removed. 
Result: void * 
Returns a pointer to the removed resource block. 


Remarks: The resource block will become independent, as though it had been allocated 
specifying NULL as its parent. 


BrResF ree () 


Description: | Free a resource block. 
Declaration: void BrResFree(void* vres) 
Arguments: void * vres 


A pointer to a resource block (previously allocated using BrResAllocate() 4, or 
BrResStrDup () 9). 


Effects: | Frees the resource block, and any dependent resource blocks it has. If any resource 
classes have destructors (see br_resource_class,,,), they are invoked when 
appropriate. 


Example: 
void BR_CALLBACK example_destructor(void* res, br_uint_8 
res_class, br_size_t size) 


{ 


#define EXAMPLE _CLASS (BR_MEMORY_APPLICATION + 1) 


static br_resource_class example={ “My 
Class”,EXAMPLE_CLASS,example_destructor}; 


{ BrResClassAdd(&example);/* Create resource class */ 


{ void *ptr; 
ptr = BrResAllocate (NULL, 1024,EXAMPLE_CLASS) ; 


BrResFree(ptr);/* Destructor is invoked */ 
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See Also: BrResClassAdd ();;; 
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Dynamic Memory 


Simple Memory Services 


While C compilers typically provide dynamic memory allocation services via the standard C library, 
to assist platform independence, BRender indirects all its requirements via an allocator data structure, 
which defines allocation, deallocation, and inquiry functions. By default these will use the standard 
C library functions (malloc and free). Note that not all development systems provide any inquiry 
functions, so in some cases the corresponding, default BRender function will return zero. Given the 
vagaries of what is meant by ‘available memory’, the application programmer is expected to 
implement this function themselves if its behaviour is critical. 


The following two functions are provided for efficient initialisation and copying of word aligned 
memory. 


BrBlockFill () 


Description: — Fast fill a block of memory. 
Declaration: void BrBlockFill(void* dest_ptr, int value, int dwords) 
Arguments: void * dest_ptr 
A pointer to the block to be filled. 
int value 
Value to fill the block with. 
int dwords 
Size of block (number of 32-bit words). 
See Also: BrBlockCopy () s: 


BrBlockCopy () 


Description: | Copy a block of memory. The source and destination blocks must not overlap. 


Declaration: void BrBlockCopy (void* dest_ptr, const void* src_ptr, 
int dwords) 
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Arguments: void * dest_ptr 


Destination pointer. 


const void * src_ptr 


Source pointer. 


int dwords 
Size of block to copy (number of 32-bit words). 
See Also: BrBlockFill() x 


Memory Classes 


For more precise control over its memory usage, BRender distinguishes between its various uses of 
dynamic memory. Memory classes also map to resource classes, given that a resource class restricts 
itself to a single memory class. So identifier’s of each are the same. 


Memory classes are defined by name and number. The following symbols define the number of each 
BRender memory class: 

BR ORY_SCRATCH 
ORY_PIXELMAP 
ORY_PIXELS 
ORY_VERTICES 
ORY_FACES 
ORY_GROUPS 
ORY_MODE 
ORY_MATERIAL 
ORY_MATE 
ORY_ACTOR 
ORY_PREPARED_VERTICES 
ORY_PREPARED_FACES 
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The class names are the same bar the BR_MEMORY prefix, thus BR_MEMORY_LIGHT has an identifier 
of “LIGHT”. 





The applications programmer may also indirectly request memory using classes between 
BR_MEMORY_APPLICATION and BR_MEMORY_MAX-1 (inclusive). BR_MEMORY_APPLICATION 
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should be used for general heap requirements (like malloc () ). Classes 
BR_MEMORY_APPLICATION+1 and onwards are reserved for user defined classes (see 
br_resource_class,,,and BrResClassAdd () ;;;). 





Dynamic Memory Services 


When allocating memory or making an inquiry, the memory class needs to be specified. For general 
purposes use BR_MEMORY_APPLICATION. 





BrMemInquire () 


Description: | Find the amount of memory available of a given type. 
Declaration: br_size_t BrMemInquire(br_uint_8 type) 
Arguments: br_uint_8 type 
Memory type. 
Result: br size_t 


Returns memory available in bytes. 


BrMemAllocate () 


Description: Allocate memory. 
Declaration: void* BrMemAllocate(br_size_t size, br_uint_8 type) 
Arguments: br_ size t size 
Size of memory block to be allocated. 
br_uint_8 type 
Memory type. 
Result: void * 


Returns a pointer to the allocated memory, or NULL is unsuccessful. 


BrMemCalloc () 


Description: — Allocate and clear memory. 
Declaration: void* BrMemCalloc(int nelems, br_size_t size, br_uint_8 type) 
Arguments: int nelems 

Number of elements to allocate. 

br_size_ t size 


Size of each element. 
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Result: 


br_uint_8 type 
Memory type. 
void * 


Returns a pointer to the allocated memory, or NULL 1s unsuccessful. 


BrMemSt rDup () 


Description: 
Declaration: 


Arguments: 


Result: 


Duplicate a string. 

char* BrMemStrDup(const char* str) 
const char * str 

A pointer to the source string. 

char * 


Returns a pointer to the new copy of the string. 


BrMemF ree () 


Description: 
Declaration: 


Arguments: 


Deallocate memory. 
void BrMemF ree (void* block) 
void * block 


A pointer to the block of memory to deallocate. 


Memory Allocation Handler 


BRender provides the facility for the application to specify their own memory allocation functions, 
through which all BRender’s memory allocation is performed. A static br_allocator,,, structure, 
containing pointers to an allocator, deallocator and inquiry function, is defined and engaged using 
BrAllocatorSet () ,;. 


The application will typically need to do this for platforms that don’t have the standard C library 
functions (malloc() etc.), and in cases where simple memory allocation is not appropriate due to 


limited memory space or performance. 


Memory Pools 


Pools are a flexible way of allocating memory from a class, whereas resource classes permit structured 
allocation. See br_pool,,, for more information. 
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Filing System Support 


Standard Filing System Services 


BRender provides a set of filing system services very similar to those provided in the standard C 
library. All filing should be performed using these functions, so that on platforms where there is no 
standard C library or where the filing system is based on an unusual media such as cartridge, calls to 
load various items will still succeed. In some cases it may be necessary to have some read operations 
accessing a CD-ROM and some read/write operations accessing a memory card (not that one expects 
to store much in a memory card). 


Note that BRender will recognise an environment variable (in some systems) called 
BRENDER_PATH, which will be used, if defined, to extend the search for unqualified file names 
beyond the current directory. 


For background information on the following functions, read any standard C library documentation 
that you may have. 


BrFileAttributes () 


Description: | Determine capabilities of the filing system. 
Declaration: br_uint_32 BrFileAttributes (void) 


Preconditions: — Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed initialisation. 


Effects: Interrogates filing system. 
Result! br_uint_32 


The attributes of the filing system; its capabilities as defined by a combination of 
the following flag values: 


Flag Attribute 

BR_FS_ATTR_READABLE Filing system can read files 
BR_FS_ATTR_WRITEABLE Filing system can write files 
BR_FS_ATTR_HAS_TEXT Filing system can interpret ASCII text files 


BR_FS_ATTR_HAS_BINARY | Filing system can support binary files, i.e. maintains integrity of 
streams of any combination of bytes (8 bit). 








BR_FS_ATTR_HAS_ADVANCE | Filing system can directly skip bytes 


BrFileOpenWrite () 


Description: | Open a file for writing, over-writing any existing file of the same name. 
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Declaration: 


Arguments: 


Preconditions: 


Effects: 
Result: 


Remarks: 


void* BrFileOpenWrite (const char* name, int mode) 
const char * name 


Name to open file as. 


int mode 











Mode in which to open file (BR_FS_MODE_TEXT or BR_FS_MODE_BINARY). In 
the default implementation of the filing system (using the standard C library), this 
is effectively turned intoa “w” or “wb” write mode parameter to fopen(). 











Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed initialisation. 


Overwrite or create file using specified name and mode. 
void * 
Return a file handle or NULL if the file could not be opened. 


In the default implementation, when a file is opened for writing in text mode, ‘end 
of file’ (EOF, Ctrl-Z, 0x1A) characters may have special significance, and ‘line 
feed’ (LF, Ctrl-J, Ox0A, ‘\n’) characters may be translated to ‘carriage return, line 
feed’ combinations. Consult your Standard C library documentation. 


BrFileWrite () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 
Result: 


Remarks: 
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Write a block of data to a file. 

int BrFileWrite(const void* buf, int size, int n, void* f) 
const void * buf 

Buffer containing block to be written. 

int size 

Size of each element in block. 

int n 

Maximum number of elements to write. 

void * f 

Valid file handle - as returned by BrFileOpenWrite () <5. 


Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed Initialisation. 


Write up ton elements from buf to the file f. 

int 

Return the number of complete elements written, which may be less thann ifan 
error occurs (such as running out of file space). 


The data written to the file may be affected by the current ‘write mode’ of the file. 
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BrFilePrintf () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 
Result: 


Remarks: 
See Also: 


Write a formatted string to a file. 

int BrFilePrintf(void* £, const char* fmt, ...) 
void * f 

Valid file handle - as returned by BrFileOpenWrite () <5. 
const char * fmt 


Format string as supplied to printf (). 


Any further necessary parameters as would be required in printf (). 


Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed initialisation. 


Write the string to the file (effectively using vsprintf () ). 

int 

Returns the number of characters written, or a negative value if an error occurs. 
The data written to the file may be affected by the current ‘write mode’ of the file. 


Consult your Standard C library documentation. 


BrFilePutLine () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 
Remarks: 
See Also: 


Write a line of text to a file, followed by writing the new-line character (’ \n’). 
void BrFilePutLine (const char* buf, void* f) 

const char * buf 

Pointer to zero terminated string containing line of text to be written. 
void * f 

Valid file handle - as returned by BrFileOpenWrite () ;.. 


Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed initialisation. 


Write the string to the file. Write the new-line character to the file (4 \n’). 
‘The data written to the file may be affected by the current ‘write mode’ of the file. 


Consult your Standard C library documentation. 


BrFilePutChar () 


Description: 


Declaration: 
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Write a single character to a file. 


void BrFilePutChar (int c, void* f) 
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Arguments: 


Preconditions: 


Effects: 
Remarks: 
See Also: 


int c 

Character to write. 

void * f 

Valid file handle - as returned by BrFileOpenWrite () ;;. 


Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed initialisation. 


Write the character to the file. 
The data written to the file may be affected by the current ‘write mode’ of the file. 


Consult your Standard C library documentation. 


BrFileOpenRead () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


Result: 


See Also: 


60 


Open a file for read access. 


void* BrFileOpenRead(const char* name, br_size_t n_magics, 
br_mode_test_cbfn* mode_test, int* mode_result) 


const char * name 
Name of file. 
br_size_t n_magics 


Number of characters required for mode_test to determine file type (less than 
or equal to BR_MAX_FILE_MAGICS). 





br_mode_test_cbfn * mode_test 

Call-back function that can be used to determine file type given the first 
n_magics characters of a file. Will not be used if NULL. 

int * mode_result 

If this argument is non-NULL, the file type (if it could be determined) will be stored 
at the address pointed to. 


Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed Initialisation. 


Searches for a file called name, if no path 1s specified with the file, looks in the 
current directory, if not found tries, in order, the directories listed in 
BRENDER_PATH (if defined). Having found the file, use mode_test (if 
supplied) to find out if the file is text, binary or unknown. Store the result through 
mode_result (if non-NULL). Obtain a handle to the file. 


void * 
Return a file handle, or NULL if the file could not be opened. 


Consult your Standard C library documentation. 
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BrFileRead () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 
Result: 


Remarks: 


See Also: 


Read a block of data from a file. 

int BrFileRead(void* buf, int size, int n, void* f) 
void * buf 

Buffer to receive block. 

int size 

Size of each element in block. 

int n 

Maximum number of elements to read. 

void * f 

Valid file handle - as returned by BrFileOpenRead () «,. 


Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed initialisation. 


Read up ton elements of size bytes from the file £ and store them in buf. 
br_size t 


Return the number of complete elements read, which may be less than n if the 
end of file is encountered before all the elements could be read. 


‘The data read from the file may be affected by the ‘write mode’ used to write the 
file. 


Consult your Standard C library documentation. 


BrFileGetLine () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 


Read a line of text (excluding terminators) from a file. 

int BrFileGetLine(char* buf, br_size_t buf_len, void* f) 
char * buf 

Buffer to hold text read. 

br_size_t buf_len 

Length of buffer (maximum number of characters to store - including ‘\0’). 
void * f 

Valid file handle - as returned by BrFileOpenRead () «,. 


Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed Initialisation. 

Read characters into supplied buffer until buf_len-1 characters have been read, 
end of line has been read, or end of file has been reached. If the last character read 
was ‘\n’ itis removed from the buffer. 
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Result: 


Remarks: 


See Also: 


int 
The number of characters stored in the buffer is returned. If at the end of file upon 
entry, zero will be returned. 


The data read from the file may be affected by the ‘write mode’ used to write the 
file. 


Consult your Standard C library documentation. 


BrFileGetChar () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 


Result: 


Remarks: 


See Also: 


Read a character from a file. 

int BrFileGetChar(void* f) 

void * f 

Valid file handle - as returned by BrFileOpenRead () «,. 

Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed initialisation. 

If the file position is at the end of the file, the file enters the end-of-file state, 
otherwise a character is read and the file position is advanced. 

int 

The character read from the file is returned (as though the character had been cast 


as (int) (unsigned char) ). Ifa character could not be read because the file 
position was at the end of the file, BR_EOF is returned. 





The data read from the file may be affected by the ‘write mode’ used to write the 
file. 


Consult your Standard C library documentation. 


BrFileAdvance () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 
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Advance the file pointer a number of bytes through a binary stream. 
void BrFileAdvance(long int count, void* f) 

long int count 

Number of bytes to advance. 

void * f 

Valid file handle - as returned by BrFileOpenRead(),, and 
BrFileOpenWrite () ;.. 


Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed initialisation. 


Advance file position by count. bytes. 
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Remarks: 


See Also: 


Filing System Support 


This function may be affected by the ‘write mode’ used to write the file. If the 
‘write mode’ is BR_FS_MODE_TEXT, the accuracy of the file pointer is not 


guaranteed (unless count is zero). 














Consult your Standard C library documentation. 


BrFileEOF () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 
Result: 


Remarks: 


See Also: 


Test a file pointer for end of file. 

int BrFileEof (const void* f) 

const void * £ 

Valid file handle - as returned by BrFileOpenRead(),, and 
BrFileOpenWrite () ;.. 


Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed initialisation. 


None. 

int 

Returns a non-zero value after the first read operation that attempts to read past the 
end of the file. It returns 0 if the current position is not end of file. 


This function may be affected by the ‘write mode’ used to write the file. If the 
‘write mode’ is BR_FS_MODE_TEXT, the result may indicate end-of-file upon 
reaching an EOF character. 














Consult your Standard C library documentation. 


BrFileClose () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 
See Also: 


Close a previously opened file. 

void BrFileClose(void* f) 

void * £ 

Valid file handle - as returned by BrFileOpenRead(),, and 
BrFileOpenWrite () ;,. 


Filing system handler dependent. BRender’s default filing system requires 
BRender to have completed initialisation. 


Close file. 


Consult your Standard C library documentation. 


Special Filing System Services 


BRender allows the application to specify how the various export functions should write data to files. 
Text mode will write data in ASCII, using text labels and expanding numbers into strings. Text mode 
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files are primarily used for debugging but can be useful to allow hand editing of input data. Binary 
mode will cause exported data to be written in binary, 1.e. a more compact, unreadable form. 


BrWriteModeSet () 


Description: 


Declaration: 


Arguments: 
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Effects: 


Result: 


Remarks: 


Instruct BRender to output data files in text or binary for subsequent ‘Save’ 
operations. 


int BrWriteModeSet (int mode) 


int mode 

















Write mode. Either BR_FS_MODE_TEXT or BR_FS_MODE_BINARY. 


Records the mode with which BRender should subsequently open files for writing 
and how data should be written to them. This will affect export functions such as 
BrModel Save () 540. 


int 
Returns the old write mode. 


The purpose of this function is primarily to indicate to BRender how it should 
output its data files, whether in compact binary form or in vaguely human readable, 
ASCII form. 


If the application produces binary and text files then it will specify the write mode 
upon opening a file for writing. 


When opening a file for read, it is opened in the same mode as it was written. 
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Diagnostic Support 


Very, very, very few programs are perfect. The compiler may generate incorrect code’, there may be 
bugs in the standard C libraries, BRender or the application may be faulty, even the user may upset 
things through copying the wrong versions of files, say. Certain aspects of the development platform, 
operating platform, and user configuration may make certain features unavailable. When it comes 
down to it, you have to expect the unexpected. Fortunately, BRender provides some facilities to 
assist in dealing with this problem. 


The first thing to do is to understand the different situations in which the unexpected can happen 

(the umbrella term of ‘Failure’ is used). This 1s covered in the following ‘Classifying Failure’ section. 
What to do when you spot failure is covered by ‘Handling Failure’ and various relevant techniques 
are covered in subsequent sections. 


Classifying Failure 


Build Errors 


Build errors are those caught in the build process by the preprocessor, compiler and linker. Syntax, 
semantic and symbol definition errors are the sort of errors that come under this description. 


BRender does not issue any of these errors. 


Logic Errors 


These are errors in the logic of the program, when it just doesn’t quite behave in the desired way. 
Some errors are caught by the compiler, others are hopefully caught by observation (from programmer 
to user testing). 


Subtle Errors 


These are errors caused by limitations of the program environment, e.g. loss of precision, rounding 
errors, numeric overflow, invalid algorithms, invalid data, etc. The best way of catching these is to use 
liberal ‘asserts’ throughout the program. 


Unexpected Failure 


The program can go catastrophically wrong, typically because of memory corruption. Examples of 
causes that might lead to such failure include: invalid arguments, incorrect bounds, incorrect casting, 
invalid pointers. The only way of catching these is either to double check everything using ‘asserts’ 
or to use third party tools that can monitor invalid memory access and dynamic memory use. 





* Only consider this as the very last resort, when you have explored every possible mode of failure in your own 


program. 
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Expected Failure 


There are known limitations within most computer environments. Time, resources, features, and 
user correctness are all things that are limited and sometimes the limit is reached. If a program is 
going to make any effort to avoid crashing it should at least cater for those occasions when failure can 
be expected. 


BRender provides various reporting facilities for handling failure. 


Handling Failure 


The situations in which failure can be caught are detailed below. Unexpected failure is sometimes 
caught, but usually for a consequential expected failure. Some systems may be able to detect invalid 
memory access and in some circumstances, it may be appropriate for the application to handle such 
exceptions. 


Unexpected Program Failure 


Errors that should not happen, i.e. assertion failures, should cause an abort in the debug build of an 
application and a fatal error message, but should be ignored in the release. The point about the use 
of ‘assert’ is that it states a fact about the state of the program at a particular point. If failure is 
expected, an assert should not be used, but another handler used instead. Predictably, if an assert 
would fail in the release, but is properly ignored, it is quite likely that the program will proceed to 
crash. It is therefore very important to be confident that no assertion can be expected to fail. 


Probable, Expected Failure 


Those cases where failure is probable and catered for do not warrant any special diagnostic treatment. 
Examples include: a user specified file not being found, a missing joystick, an unimplemented 
feature, etc. These are all very much expected failures and are either remedied by the user taking 
corrective action, or by the program using an alternative. Obviously, the program will need to keep 
the user informed, but such a failure is not considered an error. 


Minor, Expected Failure 


Those cases where failure does not significantly affect the program, but is improbable, and possibly 
surprising, can be considered minor failures. A warning should be issued in the debug build. In the 
release there will still be some informational evidence of failure, e.g. a greyed-out menu option. 


Serious, Expected Failure 


An expected failure, but only with a severe remedy available, can be considered a serious failure. An 
error message can be issued in the debug build, and an information response to the user in the release. 


Catastrophic, Expected Failure 


Unexpected failure, or expected failure with no remedy available, can be considered catastrophic 
failure. A fatal error message should be issued in the debug build, followed by abort. In the release 


6 6 Copyright © 1996 Argonaut Technologies Limited 


Diagnostic Support 


build, there should be an informational response. The likely remedy will be exit to the OS/Menu or 
restarting the application. 


Debug & Release Builds 


BRender supports the convention of only defining ‘assert’ macros when the DEBUG preprocessor 
symbol is defined. This together with likely differences in compiler options for debugging support, 
distinguishes the ‘debug’ build from the ‘release’ build of a BRender application. 





For conditional compilation depending upon debug or release builds, always use the defined state of 
the DEBUG symbol to determine the current build type. 








With DEBUG defined BR_LASSERT() and BR_VERIFY() will abort and report failure if their single 
argument evaluates to zero or NULL, without DEBUG defined, BRLASSERT() is defined as void, and 
BR_VERIFY() is defined to evaluate its argument. The ‘verify’ version is typically used to assert the 
value of an expression, that has a required side effect. 


























The programmer is expected to define ASSERT and VERIFY symbols as equivalent to BR_LASSERT 
and BR_VERIFY, rather than use ASSERT and VERIFY directly. This can also be achieved by 
explicitly using #include “brassert.h” in each source file in which this is required. 

















Debugging 

For debugging an application it is sometimes useful to write progress messages to stderr so that 
when errors are reported there is some contextual information preceding them. Such messages can 
also display the values of certain variables. The macro BR_TRACE() is defined for such a purpose, 
together with BR_TRACEO() to BR_TRACE6() which accept printf () style arguments for 
formatted output. 











Reporting Diagnostics 


Warnings, Errors and Fatal Errors are reported using the macros BR_WARNING(), BR_FAILURE(), 
and BR_FATAL (). Each takes a single string argument, and this is output to stderr. This should be 
considered a diagnostic level reporting facility and should only be used for testing purposes. The 
finished application should take a more polished approach and should tailor its response to each type 
of failure. 





There are also formatted versions of these macros taking multiple arguments. The macro has a single 
digit suffix indicating the number of arguments (from 0 to 6) in addition to the format string — the 
arguments are the same as for printf (). 


Use BR_WARNING() to generate a warning or error message, but continue with the program 
afterwards. Use BR_FAILURE() to generate an error message, and not return, but perform a recovery 
(exit). Use BR_FATAL() for severe cases where source level information (source file name and line 


number) should also be reported. 





Errors Reported by BRender 


BRender may utilise the diagnostics itself in some circumstances, e.g. a missing file, insufficient 
memory, etc. 
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Specifying a Diagnostic Handler 


A diagnostic handler may be set using BrDiagHandlerSet () ,,,. This may be to report errors more 
appropriately, e.g. in a dialog box (in a GUD), or to a remote debugging terminal. Or, it could simply 
be to disable the messages. 





The error handler lists pointers to functions handling BR_TRACE (), BR_WARNING(), 
BR_FAILURE(), and BR_FATAL(). 
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Miscellaneous 
Input Device Support 


BRender has little support for 3D specific input devices, however, the following function may be 
useful in simulating a 3D input device using a 2D input device such as a mouse. 


BrMatrix34RollingBall () 


Description: 


Declaration: 


Arguments: 


Effects: 


Remarks: 


Example: 


See Also: 


This function generates a matrix which provides an intuitive way of controlling the 
rotation of 3D objects with a mouse or other 2D pointing device. The mouse may 
be thought of as controlling a horizontal flat surface resting on top of a fixed sphere. 
As the surface is moved in any direction (but not rotated), so the sphere will rotate. 


void BrMatrix34RollingBall (br_matrix34* mat, int dx, int dy, 
int radius) 


br_matrix34 * mat 

A pointer to the destination matrix. 

int dx,dy 

‘The amount the ‘top surface’ has moved in each direction. 
int radius 

The radius of the imaginary ball. 


This function calculates the tangent vector (dx,dy) to the sphere of radius 
radius. in 3D, and uses this to determine the axis of rotation normal to this 
tangent at the centre of the sphere, and the angle subtended by the tangent vector. 
From this, a transform matrix is created, describing the rotation. 


The function is expected to be used with frequent samples of movements made 
with the 2D manipulator, i.e. a movement of 10cm in one go will produce a smaller 
rotation (no greater than 180°) whereas the same movement sampled at 100 
intervals will cumulatively produce a larger rotation (possibly several revolutions). 
This is unlikely to be a problem in practice. 


Note that using the 2D manipulator to describe small circles can rotate the 3D 
object about its vertical axis. 


int mouse_x,mouse_y; 


br_matrix34 mat; 


BrMatrix34RollingBall(&mat,-—mouse_x,mouse_y,500); 


The book Graphics Gems III, edited by David Kirk, ISBN 0-12-409670-0, Ch.2, 
Pt.3, ‘The Rolling Ball’, Andrew J. Hanson, p51. 
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Platform Specific Support 
All Platforms 


Note that the installation guide will have more detailed documentation for each platform. 


Diagnostic Support 


See br_diaghandler,,, for details of providing a platform specific, diagnostic handler. 


Dynamic Memory Support 


See br_allocator,,, for details of providing a platform specific, memory allocation handler. 


Filing System Support 


See br_filesystem,,, for details of providing a platform specific, filing system handler. 


Machine Word Ordering 


The network order of an n byte word is defined as each byte sorted in order of significance, with the 
most significant byte at offset 0, and thus the least significant byte at offset n-1. The host order of a 
word is undefined and varies across platforms. No assumptions should be made about host ordering, 
and any time anything is done which is order dependent, the word must be first converted to network 
order. BRender defines the following macros to convert between host and network ordering. 


BrNtoHF (n) Converts a float argument from network order to host order 
BrNtoHL(n) Converts a long argument from network order to host order 

BrNtoHS (n) Convertsa short argument from network order to host order 
BrHtoNF (n) Converts a float argument from host order to network order 


BrHtoNL(n) Converts a long argument from host order to network order 























BrHtoNS (n) Convertsa short argument from host order to network order 


Games consoles 


Sony PSX/Sega Saturn 


No documentation is available at the time of writing, except that these platforms are supported. 
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DOS 


MS DOS/PC DOS/DR DOS 


BRender is supported on this platform in conjunction with a 32 bit DOS extender (refer to the DOS 
installation guide). There is a DOS support API (described in the DOS platform installation guide) 
covering the following areas: 

Setting graphics modes and obtaining a video buffer 

Setting the video palette 

Obtaining mouse input 

Reading the system clock 

Keyboard handling 

Divide overflow exception handling 

Keyboard and Mouse event handling 


Specific Graphics Hardware 


No documentation on support for specific graphics hardware was available at the time of writing, 
except that VESA and VGA compliant graphics cards are supported. 


Windows (16 bit) 


Windows 3.1 & 3.11 (Win32s API) 


Note that BRender is only able to operate effectively on these platforms by using the Win32s API. 


BRender is able to render to a device independent pixel map. Displaying the pixel map requires use 
of a Windows or WinG API function such as BitBlt, StretcchDIBits, WinGBitBlt, WinGStretchBlt, etc. 


Specific Graphics Hardware 


No documentation on support for specific graphics hardware was available at the time of writing. 


Windows (32 bit) 


Windows 95 & NT (Win32 API) 


BRender is able to render to a device independent pixel map. Displaying the pixel map requires use 
of a Windows or WinG API function such as BitBlt, StretchDIBits, WinGBitBlt, WinGStretchBlt, etc. 


Direct Draw, Direct 3D 


No documentation is available at the time of writing, except that BRender will exploit these APIs. 
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Intel/Alpha/MIPS/PowerPC 


No documentation concerning any differences in BRender API or operation across these MPUs is 
available at the time of writing. 


Specific Graphics Hardware 


No documentation on support for specific graphics hardware was available at the time of writing. 


Macintosh 


68k , Power Mac 


No platform specific documentation is available at the time of writing except that this platform is 
supported. 


Other 


Other platforms may be supported, but no documentation is available at the time of writing. 





* 68020 or better 
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br_actor 


br actor 


The Structure 


The basic unit of scene construction. The br_actor,, object is designed to facilitate hierarchical 
relationships between elements of a scene, particularly in terms of position and orientation. 


See The Actor, page 12, in the structured description for further details. 


The typedef 


(See actor.h for precise declaration and ordering) 


Hierarchical relationships 


br_actor * parent Parent of this Actor 

br_actor * next Next sibling of this Actor 

br_actor ** prev Previous sibling of this Actor 

br_actor * children Children of this Actor 

br_uint_16 depth Depth of this Actor from root of hierarchy 
Positional relationship 

br_transform t Transform to convert to parent co-ordinates 
Actor function 

br_uint_8 type Actor type 

void * type_data Extra, type specific data for this Actor 
br_model * model Model data for model Actors 
br_material * material Material data for model Actors 


br_uint_8 render_style Rendering style for model Actors 
Supplementary 

char * identifier String to identify actor 

void * user User data (application dependent) 
Related Functions 


Scene Rendering 


See BrZbSceneRenderBegin () ,,, BrZbSceneRenderAdd () ,,, BrZbSceneRender () ;,, 
Br[Zb|Zs]ModelRender () 4531951 
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Members 


Hierarchical Relationships 








next 





Sibling Actors 
Linked List 





prev 








children 





Arrangement 














parent 





(root actor) 








next next 














rev rev rev 
Pp Pp B 














children children [children 


























parent parent | parent 


(child actor) (child actor) (child actor) 








At head of list when parent —> children == ‘this’ 
At end of list when next==NULL 


Diagram showing linked list of sibling actors for three children of a root. 


br_actor * parent 

A pointer to the actor’s parent actor in an actor hierarchy. If the actor has no parent, i.e. is the root 
actor of its hierarchy, parent is NULL. 

br acror -* next 

A pointer to the next sibling actor in the linked list of sibling actors (parent’s children). If the actor 
has no siblings or is the last sibling actor, next is NULL. 

Dr aclor ** prey 


A pointer to the previous sibling actor’s next member in the linked list of sibling actors (parent’s 
children). If the first sibling, prev will point to its parent actor’s children member. If the root actor, 
prev is NULL. Given that the next member is the first member of br_actor,, prev can be cast to 
a pointer to the previous actor (where prev points to a next member). 


br actor * children 


A pointer to the first actor in a linked list of child actors. If the actor has no children, children is 
NULL. 
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br_uint_16 depth 


The depth of the actor from the root of the hierarchy. depth is zero for the root actor and increases 
by one each generation (indirection through children). 


Common Features of next, prev, children, depth 


‘These members are maintained by BRender, and only ever changed during hierarchy construction 
(See BrActorAdd () ,,, BrActorRemove () ,,, BrActorRelink () ,,). Although they should never be 
directly modified, direct use for traversal purposes is permitted. 


Positional Relationship 


br_transform t 


This defines the transform to apply to co-ordinates of this actor (e.g. of models), to convert them to 
co-ordinates in its parent’s co-ordinate system. This is the primary way of defining relative model 
positions and orientations. Any valid transform may be used. 


‘This member is read when rendering and computing actor/actor transforms. It can be modified at any 
time, although it should be appreciated that this may have unpredictable effects if done during render 
call-back functions. 


See BrActorToActorMatrix34 () ,, for information on obtaining transforms between actors other 
than parent and child. 


Example 


Remember that each actor can be considered to have its own (right handed) co-ordinate system. 
Consider a point (1,2,3), of a model vertex say. Let’s suppose the actor has a transform that just 
translates by a vector of (1,0,0). In applying this transform we obtain the point (2,2,3), and these are 
now co-ordinates in the parent’s co-ordinate’s system. Now let’s suppose the actor has a transform 
that also rotates by 90° about the x-axis (+y topples toward us, +z) and is then followed by the 
translation of (1,0,0). If we applied this transform we’d obtain the point (2,-3,2). 


If you wished to perform this using BRender functions, you might first use 
BrTransformToMatrix34 () ,,,and then BrMatrix34App1]lyP () ,4,. 


Actor Function 
br_uint_8 type 


This member defines the type of function required of this actor. The actor’s type should contain a 
value defined by one of the symbols described in the following table. 
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Actor Type Symbol Behaviour 

BR_ACTOR_NONE Reference actor — no special behaviour. May be used to define frames of reference, 
actor groups, intermediate transforms, inheritable properties, and temporarily disable 
an alternative behaviour. 

BR_ACTOR_MODEL Renderable model — render the specified model in the specified style, possibly using 
the default material 

BR_ACTOR_LIGHT Light source — affects rendering of models using materials that are lit. 

BR_ACTOR_CAMERA Camera — used to define view point and perspective for rendering output image. 

BR_ACTOR_BOUNDS A cuboid bounding box, application defined within the actor’s co-ordinate space. 





Box completely off screen: rendering of all descendants is disabled 

Box partially on/off screen: descendants subject to ‘on screen’ check 

Box completely on screen: descendants subject to ‘on screen’ check 
BR_ACTOR_BOUNDS_CORRECT | A cuboid bounding box, application defined within the actor’s co-ordinate space. 

Box completely off screen: rendering of all descendants is disabled 

Box partially on/off screen: descendants subject to ‘on screen’ check 





Box completely on screen: descendants not subject to ‘on screen’ check* 
BR_ACTOR_CLIP_PLANE The four vector pointed to by type_data defines a three vector unit normal toa 

plane whose distance from the origin is represented by the fourth element. 

Descendants are clipped against the plane, with the side defined by the normal being 


‘in scene’. 


a. Rendering of a model that is off screen is undefined, and should be considered a fatal error 


Although set at initialisation, this member can be changed outside rendering at any time (as long as 
the other members are set appropriately, and, if a Light or Clip Plane, it has first been disabled (See 
BrLightDisable(),,and BrClipPlaneDisable(),,)). During rendering (within call-back 
functions) change is not recommended — Actors should not be changed to or from Lights or Clip 
Planes, and the particular Camera supplied for the rendering should not have its type changed. 


void * type_data 


This member is used to refer to additional, type specific data. It should point to data according to the 
contents of type as shown in the following table: 





Actor type Contents of type_data 
BR_ACTOR_NONE NULL (or application defined) 
BR_ACTOR_MODEL NULL (or application defined) 
BR_ACTOR_LIGHT Pointer to an instance of br_light,,, 
BR_ACTOR_CAMERA Pointer to an instance of br_camera,,, 
BR_ACTOR_BOUNDS Pointer to an instance of br_bounds jo, 
BR_ACTOR_BOUNDS_CORRECT | Pointer to an instance of br_bounds jo, 
BR_ACTOR_CLIP_PLANE Pointer to an instance of br_vector4,,, 


The type_data member should not be NULL except for BR_LACTOR_NONE or BR_ACTOR_MODEL. 


This member can be changed at any time, though not recommended during rendering. 
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Experienced C programmers will be familiar with the technique of supplying pointers to structures 
that are actually embodied within others, for the purpose of accessing attached application specific 
data’. This technique is still a workable way of extending the amount of data within BRender data 
structures, particularly here’. For example, it may be desired to introduce rotating lights. The 
corresponding details could be appended to the br_light,,; structure as demonstrated in this 
example: 


typedef struct /* My light, which can be used instead of 
br_light */ 

{ br_light light; /* The standard BRender light specification */ 
unsigned type; /* My extended light type */ 
br_scalar speed; /* Various properties */ 
br_vector3 axis; 


} my_light; 


br model * model 


The model defines the geometry and any specific face characteristics to be rendered in this actor’s 
co-ordinate space. 


This member points to model information, which is used by this actor if it is a model actor, and 
descendent model actors that inherit it. If NULL, model information is obtained (when required by a 
model actor) from the previous ancestor (parent) that supplied it. If no ancestor supplies it, a default 
br_model1,,, data structure is used which defines a cube (this is for diagnostic purposes only). 


Note that an actor does not have to be a model actor in order for it to define a model to be inherited 
by a descendent model actor. 


br_material * material 


The material is used for a model’s faces that don’t specify a material. 


This member points to material information, which is used by this actor if it is a model actor, and 
descendent model actors that inherit it. If NULL, material information is obtained (when required by 
a model actor) from the previous ancestor (parent) that supplied it. If no ancestor supplies it, a default 
br_material,,, data structure is used which defines a flat-shaded grey (this is for diagnostic 
purposes only). Out of interest, it is currently defined as follows:* 





* For C++ programmers, this is embraced by the language — any derived class may be supplied where a base class 
is expected. 

+ Though BRender will of course, not be aware of any attached data (so will not save it in BrActorSave (), 
say). 

£ Yet subject to change 
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{ "default", 
BR_COLOUR_RGB (255,255,255), /* colour */ 
255, /* opacity */ 
BR_UFRACTION (0.10), /* Indexed ka */ 
BR_UFRACTION (0.70), /* ka */ 
BR_UFRACTION(0.0), /* ks */ 
BR_SCALAR (20), /* power */ 
BR_MATF_LIGHT, /* flags */ 
{{ BR_VECTOR2 (1,0), /* map transform */ 


BR_VECTOR2 (0,1), 
BR_VECTOR2 (0,0), 


}}, 
0,63; /* index base/range*/ 
}; 


Note that an actor does not have to be a model actor in order for it to define a material to be inherited 
by a descendent model actor. 


br_uint_8 render_style 


This member determines the style of rendering, which is used by this actor if it is a model actor. If 
the NULL style (BR_RSTYLE_DEFAULT) is specified, the rendering style is obtained (when required by 
a model actor) from the first ancestor (from the root) that defines a non-NULL style. If no ancestor 
defines one, the model is rendered as though BR_RSTYLE_FACES had been specified. 


This is subtly different from normal inheritance, in that non-default styles set by intervening actors 
have no effect. It is designed this way to facilitate the use of an attribute primarily intended for 
highlighting (obviously not one concerned with realism). 


The render_style member should be set to a value defined by one of the following (enum) 
symbols: 


Rendering Style Symbol Rendering Effect 


BR_RSTYLE_DEFAULT Uses first non-default rendering style defined in this branch of the hierarchy 
(renders faces if no non-default style defined). 

BR_RSTYLE_NONE Does not render this actor or any of its descendants. 

BR_RSTYLE_POINTS Renders only the points at each vertex of a face using the model’s material. 

BR_RSTYLE_EDGES Renders only the points along each edge of a face using the model’s material.(see 
br_face,,,, flags) 

BR_RSTYLE_FACES Renders all the points across rendered faces using the model’s material. 

BR_RSTYLE_BOUNDING_POINTS | Renders only the points at each vertex of the model’s bounding box using the 


actor’s material 


BR_RSTYLE_BOUNDING_EDGES Renders only the points at along edge of the model’s bounding box using the 
actor’s material 














BR_RSTYLE_BOUNDING_FACES Renders the faces of the model’s bounding box using the actor’s material 
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Supplementary 


char * identifier 


Pointer to unique, zero terminated, character string (or NULL if not required). Can be used as a handle 
to retrieve a pointer to the actor, given only an ancestral actor. Not intended for intensive use. 
Typically used to collect pointers to actors loaded using BrActorLoad (),., and 

BrActorLoadMany () ,... Also ideal for diagnostic purposes. 


A non-unique string can be supplied, but which of a set of actors having the same string will be 
matched by search functions (See BrActorSearch ().,), is undefined. Also in consideration of 
searching, it is not recommended that non-alphabetic characters are used, especially Slash 

(‘7’), Asterisk (‘*’), and Query (‘?’), which are used for pattern matching. 


This member can be modified by the programmer at any time. 


If identifier is set by BrActorLoad (),, or BrActorLoadMany () ,), it will have been constructed 
using BrResStrDup () 4. 


void* user 


This member may be used by the application for its own purposes. It is initialised to NULL upon 
allocation, and not accessed by BRender thereafter. 


Operations 


Hierarchical Relationships 


BrActorAdd () 


Description: | Add an actor hierarchy as a child of a given parent. 
Declaration: br_actor* BrActorAdd(br_actor* parent, br_actor* a) 
Arguments: br_actor * parent 

Anon-NULL pointer to the parental actor. 


br_actor *a 





Anon-NULL pointer to its new child. 


Preconditions: Between BrBegin () ,, & BrEnd(),,. New child must be root of its hierarchy, Le. 
must not still be child of another parent. 

Effects: | Parent’s children member may be modified. Added hierarchy will be linked 
into linked list of parent’s children. Members next and prev ofsome of parent’s 
children and of added hierarchy will be modified. The parent member of the 
added hierarchy will be modified. All depth members of added hierarchy will be 
updated. 
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Result: 


Remarks: 


See Also: 


br_actor 


br_actor * 
The new child pointer a _ is returned as supplied (for convenience). 


Do not attempt to add an actor at more than one place in a hierarchy at a time — 
BRender currently only supports simple hierarchical actor structures, not directed 
acyclic (or cyclic) graph structures. Note that in spite of this restriction, models on 
the other hand, may be simultaneously referred to by any number of actors. 


BrActorRemove (),;;, BrActorRelink () ,; 


BrActorRemove () 


Description: 
Declaration: 


Arguments: 


Preconditions: 
Effects: 


Result: 


Remarks: 
See Also: 


Remove an actor hierarchy from its parent. 

br_actor* BrActorRemove (br_actor* a) 

br_actor * a 

Anon-NULL pointer to the hierarchy to remove. 

Between BrBegin () ,, & BrEnd() ,,. Actor to remove must be a child. 


Parent’s children member may be modified. Removed hierarchy will be 
unlinked from linked list of parent’s children. Members next and prev of some 
of parent’s children and of removed hierarchy will be modified. The parent 
member of the removed hierarchy will be modified. All depth members of 
removed hierarchy will be updated. 


br_actor * 

The pointer to the removed hierarchy is returned as supplied (for convenience). 
Note that a Light or Clip plane actor must be disabled before it is removed. 
BrActorAdd(),,, BrActorRelink (),, 


BrActorRelink () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 
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Move an actor in a hierarchy, but preserve its apparent world transformation by 
manipulating its own transformation as necessary. 


void BrActorRelink (br_actor* parent, br_actor* a) 
br_actor * parent 
Anon-NULL pointer to the new parent. 


br_actor * a 





Anon-NULL pointer to the actor to move. 


Between BrBegin () ,, & BrEnd () ,,. Both supplied actors are in the same 
hierarchy. 


Equivalent to a call of BrActorRemove (a) ,; followed by 
BrActorAdd (parent,a) ., except that the moved actor’s transform is modified 
to reproduce the effects of the original transform. 
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Remarsk: 
See Also: 


Note that a light or clip plane actor must be disabled before it is relinked. 
BrActorAdd(),,, BrActorRemove () ,; 


Positional Relationship 


BrActorToActorMatrix34 () 


Description: 


Declaration: 


Arguments: 


Preconditions: 
Effects: 


Result: 


Accumulate the transformations between one actor and another, representing the 
result as a matrix. 


br_uint_8 BrActorToActorMatrix34 (br_matrix34* m, 
const br_actor* a, const br_actor* b) 


br_matrix34 * m 


Anon-NULL pointer to the destination matrix, into which will be placed the 
transform. 


const br_actor * a 


Anon-NULL pointer to the actor from whose co-ordinate space co-ordinates are to 
be transformed. 


const br_actor * b 


Anon-NULL pointer to the actor into whose co-ordinate space co-ordinates are to 
be transformed. 


Between BrBegin () ,, & BrEnd() ,,. Both actors must be in the same hierarchy. 


Will calculate the transform required to transform co-ordinates in the co-ordinate 
space of a, into the co-ordinate space of b. 


br_uint_8 


The type of the accumulated transformation, e.g. BR_TRANSFORM_MATRIX34 (see 
br_transform,,,). 


BrActorToBounds () 


Description: 


Declaration: 


Arguments: 


Preconditions: 
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Compute an actor hierarchy’s bounding box, encompassing the bounding box of all 
models (including descendants). 


br_bounds* BrActorToBounds (br_bounds* b, 


br_bounds * b 


const br_actor* ap) 


Non-NULL pointer to resulting bounding box. 


const br_actor * ap 





Non-NULL pointer to actor whose bounding box is required. 
Between BrBegin () ,, & BrEnd () ,,. 
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Effects: 


Result: 


Remarks: 


See Also: 


br_actor 


Obtains smallest bounding box (in this actor’s co-ordinate space) that will contain 
any model or descendant model. 


br_bounds * 
The bounding box result pointer b is returned as supplied (for convenience). 


The default model is used in cases where a model actor would inherit from an 
ancestor of the supplied actor. 


BrBoundsToMatrix34 () jo, BeScenePick3D (),,, br_bounds ,,,, 
br_model1,,,. 


BrScenePick3D () 


Description: 


Declaration: 


Arguments: 


Result: 


See Also: 


‘Traverse an actor hierarchy and invoke a call-back function for each model actor 
whose bounds intersect a given bounds in a given reference actor’s space. If the 
call-back returns a non-zero value, traversal halts. 


int BrScenePick3D(br_actor* world, 
const br_actor* reference, const br_bounds* bounds, 
br_pick3d_cbfn* callback, void* arg) 


br_actor * world 


A pointer to the root of a world hierarchy. 


const br_actor * reference 


A pointer to the reference actor. 


const br_bounds * bounds 


A pointer to a bounds structure. 

br_pick3d_cbfn * callback 

A pointer to a pick-3D call-back function. 

void * arg 

An optional argument to pass to the call-back function. 

int 

If the call-back returns a non-zero value and traversal halts, that value is returned. 
Otherwise, zero is returned. 


BrScenePick2D () 


BrActorToScreenMatrix4 () 


Description: 


Declaration: 


Accumulate the transformations between an actor and the screen, representing the 
result as a matrix. 


void BrActorToScreenMatrix4 (br_matrix4* m, 
const br_actor* a, const br_actor* camera) 
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Arguments: 


Remarks: 


See Also: 


br_matrix4 * m 


Anon-NULL pointer to the destination matrix to receive the transform between 
homogenous co-ordinates in the actor’s co-ordinate space into the homogenous 
screen space. 


const br_actor * a 
Anon-NULL pointer to an actor. 


const br_actor * camera 





Anon-NULL pointer to a camera actor. 


The function BrMatrix4App]lyP (),,, is typically used with this function to 
convert co-ordinates in an actor’s co-ordinate space into homogenous screen space 
(assuming a centred projection). Note though that the resultant 4-vector is a set of 
homogenous co-ordinates and thus the x, y and z values will need to be divided by 
the w component. 


See Homogenous screen space, page 23. 


BrMatrix4Perspective () 5s. 


BrScenePick2D () 


Description: 


Declaration: 


Arguments: 
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Result: 


‘Traverse a world hierarchy, picking model actors from the scene by casting a ray 
through a given viewport pixel attached to a given camera. A call-back is invoked 
for each actor whose bounds intersect the ray. If the call-back returns a non-zero 
value, traversal halts. 


int BrScenePick2D (br_actor* world, const br_actor* camera, 
const br_pixelmap* viewport, int pick_x, int pick_y, 
br_pick2d_cbfn* callback, void* arg) 


br_actor * world 


A pointer to the root of a world hierarchy. 


const br_actor * camera 


A pointer to a camera actor. 

const br_pixelmap * viewport 

A pointer to the viewport through which the pick ray passes. 

int pick_x, pick_y 

Co-ordinates of viewport pixel through which the pick ray passes. 
br_pick2d_cbfn * callback 

A pointer to a pick-2D call-back function. 

void * arg 

An optional argument to pass to the call-back function. 

int 

If the call-back returns a non-zero value and traversal halts, that value is returned. 
Otherwise, zero is returned. 


Copyright © 1996 Argonaut Technologies Limited 


See Also: 


Actor Function 


br_actor 


BrScenePick3D () ,,, BeModelPick2D (),,; 


BrEnvironmentSet () 


Description: 


Declaration: 


Arguments: 


Result: 


Remarks: 


This function is relevant to model actors using environment mapping (set in their 
materials’ flags member by using BR_MATF_ENVIRONMENT_I or 
BR_MATF_ENVIRONMENT_L). 


It set a new environment anchor for such model actors. By default, the reflective 
effect produced by an environment map on the surface of a model appears to rotate 
with the model itself. If this is unsatisfactory, the map can be anchored to an actor. 
If the actor is the root of a world hierarchy, then reflection effects will appear more 
realistic. 


br_actor* BrEnvironmentSet (br_actor* a) 

br_actor * a 

A pointer to an actor to which all environment maps should be anchored. If NULL, 
environment maps are not anchored, but rotate with models. 

br_actor * 

Returns a pointer to the old environment anchor. 


Environment actors must be part of the rendered scene (a descendant of the 
effective root). If rendering a scene to produce a reflection environment map in 
another scene, then (unless the reflected scene also involves environment maps) 
the function should be called with NULL before the reflected scene is rendered, 
and then called with an appropriate anchor actor (that is part of the latter scene, in 
which the environment map is used). 


BrLightEnable () 


Description: 


Declaration: 


Arguments: 


Enable a light actor’s effect as a light source within the scene. Light actors only 
affect the lighting of a scene if they are in the enabled state before rendering. 


void BrLightEnable(br_actor* 1) 
br_actor * 1 


Anon-NULL pointer to a light actor. 
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Remarks: 


See Also: 


By default, light actors are disabled. 


Light actors must be in the disabled state before they are removed from, relinked 
within, or added to a hierarchy. They must also be disabled before they are freed 
(or a parent is). 


For optimum performance, disable all lights known to have insignificant effect 
upon the scene. Some platforms are limited in the number simultaneously enabled 
lights that they can support. 


BrLightDisable () ,, 


BrLightDisable () 


Description: 


Declaration: 


Arguments: 


Remarks: 


See Also: 


Disable a light actor’s effect as a light source within the scene. Light actors only 
affect the lighting of a scene if they are in the enabled state before rendering. 


void BrLightDisable(br_actor* 1) 

br_actor * 1 

Anon-NULL pointer to a light actor. 

By default, light actors are disabled. 

Light actors must be in the disabled state before they are removed from, relinked 


within, or added to a hierarchy. They must also be disabled before they are freed 
(or a parent is). 


For optimum performance, disable all lights known to have insignificant effect 
upon the scene. Some platforms are limited in the number of simultaneously 
enabled lights that they can support. 


BrLightEnable () ; 


BrClipPlaneEnable () 


Description: 


Declaration: 


Arguments: 
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Remarks: 


Enable a clip plane. Such clip plane actors affect the contents of a scene (as long as 
they are enabled before rendering). 


void BrClipPlaneEnable(br_actor* cp) 
br_actor * cp 
Anon-NULL pointer to a clip plane actor. 


By default, clip planes are disabled. 


Clip planes must be in the disabled state before they are removed from, relinked 
within, or added to a hierarchy. They must also be disabled before they are freed 
(or a parent is). 
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BrClipPlaneDisable () 


Description: Disable a clip plane. 
Declaration: void BrClipPlaneDisable(br_actor* cp) 
Arguments: br_actor * cp 
Anon-NULL pointer toa clip plane actor. 
Remarks: — By default, clip planes are disabled. 
Clip planes must be in the disabled state before they are removed from, relinked 


within, or added to a hierarchy. They must also be disabled before they are freed 
(or a parent is). 


Copy/Assign 


While it may be sensible to copy some members, it is generally not sensible to copy the actor as a 
whole. 


Access & Maintenance 


Given that the order in which a hierarchy is rendered is not defined, the benefits of modifying 
members during rendering are doubtful. The structure of the actor hierarchy should not be modified 
during rendering. 


An actor may be indirectly accessed by BRender library functions if they are called while the actor is 
in a hierarchy that is thus modified or traversed (through rendering or otherwise). Consequently, 
particular care must be taken if modifying the actor while such indirect accesses may be taking place 
(especially within rendering call-back functions). 


The only functions that indirectly modify an actor’s public members are BrActorAdd () »), 
BrActorRemove () ,,, BrActorRelink (),,and BrActorFree (),,, and these only affect some or all 
of the parent, next, prev, children and depth members. 


If using the Z-Sort renderer it is likely that order tables will be need to be assigned to model actors 
on an individual basis. The following two functions are provided to specify and access an actor’s order 
table. 


No maintenance is required, except to ensure that members are valid. Hierarchical changes 
(Additions, Removals) are effected immediately (given that these are only performed by BRender 
functions). All ramifications of other changes will be effected each rendering. 


See br_model,,, and br_material,,, for their maintenance requirements. 


BrZsActorOrderTableSet () 


Description: | Given a model actor, set the order table into which its primitives will be sorted. 
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Declaration: 


Arguments: 


Effects: 


Result: 


Remarks: 
See Also: 


br_order_table* BrZsActorOrderTableSet (br_actor* actor, 
br_order_table* order_table) 


br_actor * actor 
A non-NULL pointer to a model actor. 


br_order_table * order_table 


A pointer to an order table. NULL if the actor is to inherit an order table (the default 
condition). 


Assigns the specified order table to the actor, replacing the current one if any. Be 
very careful, if assigning an order table to more than one model actor (whether 
explicitly or by inheritance). In such cases judicious use of the order table flags, 
such as BR_ORDER_TABLE_NEW_BOUNDS, may be required within a custom model 
call-back function. 





br_order_table * 
Returns order_table as supplied (for convenience). 
Only useful to model actors involved during rendering by the Z-Sort renderer. 


BrZsActorOrderTableGet () 


BrZsActorOrderTableGet () 


Description: 


Declaration: 


Arguments: 


Result: 


Remarks: 
See Also: 


Given a model actor, obtain a pointer to the currently set order table (into which its 
primitives will be sorted). 


br_order_table* 
BrZsActorOrderTableGet (const br_actor* actor) 


const br_actor * actor 
A non-NULL pointer to a model actor. 
br_order_table * 


Returns the order table currently assigned to the specified actor. NULL is returned 
if no order table is explicitly assigned, 1.e. an order table is inherited. 
Only useful to model actors involved during rendering by the Z-Sort renderer. 


BrZsActorOrderTableSet () 


Referencing & Lifetime 


References are maintained to enabled Light or Clip Plane actors even if they are subsequently 
detached from a hierarchy that is then rendered. Thus it is important to disable such actors before 


removing them. 


Actors must be maintained while they are part of an actor hierarchy, especially ones that will be 


rendered. 
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If the actor was allocated using BrActorAllocate (),, it will be freed by BrEnd () ,, (if it hadn’t been 
freed previously — as it should have been). 


Initialisation 


The actor is automatically initialised by BrActorAllocate (),,, however, if you allocate it yourself, 
you should either use calloc(, sizeof (br_actor)) ormemset(,0,sizeof(br_actor) ), 
and ensure the following is done: 

Set parent, next, prev, children to NULL 

Set depth to zero 

Set t to the identity transform 

Set type to any valid actor type 

Set model to NULL 

Set material to NULL 

Set render_style be BR_RSTYLE_DEFAULT 

Set type_data to point to a valid data structure according to the type. 

Set identifier to NULL 














Refer to the respective description of each member for further details. 


Construction & Destruction 


Actors should be constructed using BrActorAllocate (),, and destroyed using BrActorFree ().). 
Although actors can be constructed any other way (as long as they observe the access & lifetime 
requirements), they should be detached (See BrActorRemove ();;) from a hierarchy before any 
ancestor (parent) is freed using BrActorFree ().,. This is because BrActorF ree () ,, will attempt to 
release storage for all of an actor’s descendants — whether or not they were allocated by 
BrActorAllocate().,. In general, actors should be destroyed strictly using the complementary 
method of construction. 


Note that BrActorLoad (),,and BrActorLoadMany () j) will effectively call BrActorAllocate () », 
for each actor they import. 


BrActorAllocate () 


Description: — Allocate a new actor. 


Declaration: br_actor* BrActorAllocate(br_uint_8 actor_type, 
void* type_data) 
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Arguments: 


Preconditions: 


Effects: 


Result: 


Remarks: 


Example: 


See Also: 


br_uint_8 actor_type 


Defines the type member of the actor allocated (See the type member of 
br_actor,, fora list of acceptable types). It is also used to determine suitable type 
specific data if NULL is supplied for the type_data argument. 


void * type_data 


A pointer to optional, additional, type specific data used to determine the 
type_data member of the actor allocated. (See the type_data member of 
br_actor,, to determine the type of data structure that should be referenced). 
NULL may be supplied in all cases. 


Between BrBegin () ,, & BrEnd () ,,. 


Memory can be allocated. 


Abr_actor,, data structure is allocated and initialised (See br_actor,,, 
Initialisation). Its t ype member is initialised with the value of actor_type. 
Where the actor requires type specific data, and NULL has been supplied, the 
type_data member is initialised with a pointer to an appropriate, freshly 
allocated data structure containing default values. 


br_actor * 
A pointer to the new br_actor,, data structure. 


If this function allocates type specific data, it is allocated and attached to the actor 
using BrResAllocate () .., so will be freed with the actor even if the actor’s 
type_data member is subsequently changed. Until the actor is freed, the data 
may be freely accessed. 


br_actor * t_pActor=BrActorAllocate (BR_ACTOR_MODEL, NULL) ; 


BrActorFree () ») 


BrActorF ree () 


Description: 
Declaration: 


Arguments: 


Preconditions: 
Effects: 
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Free an actor and all its descendants (children) if any. 
void BrActorFree(br_actor* a) 
br_actor * a 


A pointer to an actor previously allocated using BrActorAllocate () ,,. NULL is 
not acceptable. If a Light, or Clip Plane actor, it should have first been disabled. 
The actor should have first been detached from any hierarchy by using 
BrActorRemove () ;;. 


Between BrBegin () ,, & BrEnd () ;;. 


Effectively applies BrActorRemove () ,, and BrActorFree ().,. to each child of 
the actor. Calls BrResFree () ;, to release storage for the actor and any attached 
data (e.g. type specific data created by default). 
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Remarks: | Not recommended to be applied to an actor during rendering of the hierarchy that 
it is part of. 


Ensure that any references to the actor or its children will not be used subsequent 
to this call. Remember that a light or clip plane should be disabled before it is 
removed and freed. 


Example: 
br_actor * t_pActor=BrActorAllocate(BR_ACTOR_MODEL,NULL) ; 
BrActorFree(t_pActor) ; 


See Also: BrActorAllocate (),, 


BrResFree () ;, 


Supplementary 


BrActorEnum () 


Description: | Enumerates an actor’s children, calling a user supplied call-back function for each 
child actor. 


Declaration: br_uint_32 BrActorEnum(br_actor* parent, 
br_actor_enum_cbfn* callback, void* arg) 


Arguments: br_actor * parent 
A pointer to the actor whose children are to be enumerated. 
br_actor_enum_cbfn * callback 
A pointer to the call-back function to be called for each child actor. 
void * arg 
The argument to pass to the call-back function (use NULL if not required). 
Preconditions: | Between BrBegin () ,, & BrEnd () ,). 


Effects: For each child of parent, callback is invoked supplied with a pointer to the 
child and the arg pointer. If callback returns a non-zero result, the 
BrActorEnum (),; function will immediately return with the same result, 
otherwise the enumeration continues until all children have been enumerated. 


Result: br_uint_32 
The result is zero, or the first and only non-zero result returned by callback. 


Remarks: — An entire actor hierarchy can be enumerated simply by having the call-back 
function invoke BrActorEnum () ,.; itself. 
Example: 
br_uint_32 BR_CALLBACK CountDescendantsCB(br_actor* a,void* n) 
{ +4+* (int*)n; 


return BrActorEnum(a,CountDescendantsCB,n) ; 
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See Also: 


int CountDescendants(br_actor* a) 


{ 


int N=0; 
BrActorEnum(a,CountDescendantsCB, &N) ; 


return N; 


br_actor_enum_cbfn,,, 


BrActorSearch () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


94 


Effects: 


Result: 


Remarks: 


‘Traverse an actor’s descendants, searching for an actor of a particular generation 
with a lineage and identifier matching a specified wild carded string. To find actors 
anywhere within a hierarchy will require the additional use of BrActorEnum () ,;. 


br_actor* BrActorSearch (br_actor* root, const char* pattern) 
br_actor * root 


A pointer to an actor. 


const char * pattern 


Zero terminated character string containing the search pattern. This specifies the 
generation of actor required by separating descendants with slash characters 
(‘7’), e.g. “/<Child>/<Grand-child>/<Great grand-child>/etc.”. 
Identifiers of actors along the lineage may be matched exactly or in combination 
with the wild-card characters ‘*’ (match any number of any characters) and ‘?’ 
(match any single character). The pattern is fully permuted, e.g. “b*an?s” will 
match “bananas”, “banks”, and “bandstands”. 


Between BrBegin () ,, & BrEnd () ;;. 
Compares the actor’s descendants’ identifiers with the respective component of 


the search pattern. Terminates as soon as the complete lineage matches, or all 
possible matching lineages have been explored. 


br_actor * 


A pointer to the first actor that was found whose lineage matched the search 
pattern, or NULL if there was no match. 


Note that the search pattern’s first generation will be compared with the identifiers 
of the children of root — the identifier of root is not involved in the pattern 
matching process. 


Where more than one match is possible, it is not recommended that any reliance be 
placed on which match is found first. No assumption should be made regarding 
how the actor hierarchy is traversed, e.g. whether branch by branch or generation 
by generation. 


To find an actor irrespective of its lineage, use this function in combination with 
BrActorEnum () ,;. 
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Example: | Given a root actor with identifier “Root”, children “Child1” and “Child2”, 
and child “Child1” with grand-children “Grand-son1” and “Grand- 
daughter1”, and child “Child2” with grand-children “Grand-son2” and 
“Grand-daughter2”: 


“Child?/Grand*1” would match either “Grand-son1” or “Grand- 
daughterl1”. 


“Child1” would match “Child1”. 


“x /* son?” would match either “Grand-son1l” or “Grand-son2”. 


See Also: BrActorSearchMany (),; 


BrActorEnum (),.; 


BrActorSearchMany () 


Description: ‘Traverse an actor’s descendants, searching for actors of a particular generation with 
a lineage and identifier matching a specified wild carded string. 


Declaration: br_uint_32 BrActorSearchMany (br_actor* root, 
const char* pattern, br_actor** actors, int max) 


Arguments: br_actor * root 


A pointer to an actor. 

const char * pattern 

Zero terminated character string containing the search pattern. This specifies the 
generation of actor required by separating descendants with slash characters 
(‘/’), e.g. “/<Child>/<Grand-child>/<Great grand-child>/etc.”. 
Identifiers of actors along the lineage may be matched exactly or in combination 
with the wild-card characters ‘*’ (match any number of any characters) and ‘?’ 
(match any single character). The pattern is fully permuted, e.g. “b*an?s” will 
match “bananas”, “banks”, and “bandstands”. 


br_actor ** actors 


A pointer toa series of actor pointers. Storage must have been allocated (though not 
necessarily initialised) for at least max actor pointers. 
int max 
The maximum number of matched actors to store at actors. 
Preconditions: Between BrBegin () ,, & BrEnd () ,,. 


Effects: | Compares the actor’s descendants’ identifiers with the respective component of 
the search pattern. Terminates as soon as the number of complete lineage matches 
has reached max, or all possible matching lineages have been explored. 


Result: br_uint_32 


The number of matched actors stored at actors. This will be between zero and 
max (inclusive). 
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Remarks: The same as BrActorSearch () ,, except that it allows matches of more than one 
actor. 


Note that the search pattern’s first generation will be compared with the identifiers 
of the children of root — the identifier of root is not involved in the pattern 
matching process. 


To find actors irrespective of their lineage, use this function in combination with 
BrActorEnum () ,;. 


Example: 
br_actor* t_aActorWheels[10]; 


int t_n; 


t_n=BrActorSearchMany (pActorLorry, ”Chassis/*Axle/ 
Wheel?”,t_aActorWheels,10); 


ASSERT (! (t_n%2));/* Even number of wheels */ 


See Also: BrActorSearch(),,, BrActorEnum () ,, 


Import & Export 


Actor hierarchies can be saved and loaded in their entirety. This can be useful for setting up scenes, 
or importing arbitrary, complex systems. 


BrActorFileCount () 


Description: — Locate a given file and count the number of actor hierarchies stored in it. 


Declaration: br_uint_32 BrActorFileCount (const char* filename, 
br_uint_16* num) 


Arguments: const char * filename 


Name of the file previously created by BrActorSave(),, or 
BrActorSaveMany () .) (See Filing System Support, page 57). 

br_uint_16 * num 

Pointer to destination into which the number of actor hierarchies will be stored. If 


NULL, the file will still be located and the success result returned, but no count will 
be made. 


Preconditions: Between BrBegin() ,, & BrEnd () ,,. Filing system available. 
Effects: | Searches for filename, if no path specified with file looks in current directory, if 
not found tries, in order, the directories listed in BRENDER_PATH (if defined). 


Counts the number of actor hierarchies stored in the file. If the file is not an actor 
file, the function is still successful, but would obviously produce a zero count of 
actors. 
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Result: br_uint_32 
Returns zero if successful (the file was found), non-zero otherwise. 


See Also: BrActorLoad().,;, BrActorLoadMany () , 


BrActorSave () 


Description: | Saves an actor and its descendants as a hierarchy. 


Declaration: br_uint_32 BrActorSave(const char* filename, 
const br_actor* actor) 


Arguments: const char * filename 


The name of the file under which the hierarchy should be saved (See Filing System 
Support, page 57). 


const br_actor * actor 
A pointer to the effective root actor of the hierarchy to be saved. 


Preconditions: Between BrBegin () ,, & BrEnd () ,,. Available filing system. Success depends on 
sufficient file space. 


Effects: If successful, the actor is written to a file’ along with the identifier of its 
material (if non-NULL), the identifier of its model (if non-NULL), and any type 
specific data. This same process is then applied to each child in turn. 


Result: br_uint_32 
The result is one if the hierarchy was saved successfully, and zero if not. 
Remarks: _ If the function fails (returns zero), the filing system can be considered returned to 


the state it was in just before the call, e.g. no file created. 


The hierarchical relationship between actors is recorded implicitly, no use is made 
of the actor’s parent, next, prev, children, or identifier members. 





Note, that model and material data is not saved with actors, therefore this should 

be saved separately if required. It will need to be available to BeModel1Find () 94, 

and BrMaterialFind () ,,; (in the registry) before the actor hierarchy is loaded. 
Example: 


return BrActorSave (“MyScene”, pActorScene) ; 


See Also: BrActorLoad().., BrActorSaveMany () .,, BreWriteModeSet () «, 


BrActorLoad () 


Description: — Load a hierarchy of actors from a file. 





* — Any existing file of the same name is overwritten. 
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Declaration: 


Arguments: 


Preconditions: 


Effects: 


Result: 


Remarks: 


Example: 


See Also: 


br_actor* BrActorLoad(const char* filename) 
const char * filename 


Name of the file previously created by BrActorSave (),, or 
BrActorSaveMany () . (loads the first hierarchy) (See Filing System Support, 
page 57). 

Between BrBegin () ,, & BrEnd () ,,. Filing system available. Memory can be 
allocated. 


Searches for filename, if no path specified with file looks in current directory, if 
not found tries, in order, the directories listed in BRENDER_PATH (if defined). 





Allocates a root actor, reads members (type, identifier, render_style, t) 
in the order they were saved in, attempts to set model with BrModelFind () 94, 
using the model identifier read, attempts to set material with 
BrMaterialFind() |; using the material identifier read, allocates and sets the 
type specific actor data. Any child actors are read using this same process (thus 
recursively), and then added to this actor using BrActorAdd () ,.. Ifa model or 
material was not found, the member is left at NULL. 


br_actor * 
A pointer to the root actor of the loaded hierarchy, or NULL if unsuccessful. 


Ensure that necessary models and materials are loaded and added into the registry 
before calling this function. 


br_actor* t_pMyScene=BrActorLoad(“MyScene”) ; 


BrActorSave(),,, BrActorLoadMany () , 


BrActorSaveMany () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


98 


Saves a series of actors and their descendants as hierarchies. 


br_uint_32 BrActorSaveMany (const char* filename, 
const br_actor* const * actors, br_uint_16 num) 


char * filename 


The name of the file under which the hierarchies should be saved (See Filing 
System Support, page 57). 
const br_actor * const * actors 


A pointer to a series of num pointers to effective root actors of the hierarchies to be 
saved. The actors do not necessarily need to be from unrelated hierarchies. 


br_uint_16 num 
Number of hierarchies to save. 


Between BrBegin () , & BrEnd () ,,. Available filing system. Success depends on 
sufficient file space. 
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Effects: 


Result: 


Remarks: 


Example: 


See Also: 


br_actor 


If successful for every one of the actor hierarchies, each is saved as described in 
BrActorSave (),,, except that all are written to the same file’. 


br_uint_32 


The function returns the number of complete actor hierarchies that were written to 
the file. This will be between zero and num (inclusive). Success is indicated by the 
return value being equal to num. 


If the function fails (returns a value less than num), the filing system can be 
considered returned to the state it was in just before the call, e.g. no file created. 


Note, that model and material data is not saved with actors, therefore this should 

be saved separately if required. It will need to be available to BeMode1Find () »,, 
and BrMaterialFind () ,,; (in the registry) before any of the actor hierarchies are 
loaded. 


br_actor* apActorsInMyScene[N]; 


if 


(BrActorSaveMany (“MyScene”, apActorsInMyScene, (br_uint_16)N) <N) 


BrActorLoadMany () ,», BrActorSave (),,, BeWriteModeSet () «, 


BrActorLoadMany () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Load one or more hierarchies of actors from a file. 


br_uint_32 BrActorLoadMany (const char* filename, 
br_actor** actors, br_uint_16 num) 


const char * filename 


Name of the file previously created by BrActorSaveMany ().) or 
BrActorSave (),,. See Filing System Support for details of file naming. 


br_actor ** actors 


A pointer to a series of actor pointers. Storage must have been allocated (though not 
necessarily initialised) for at least num actor pointers. See 
BrActorFileCount (),, for a way of determining this value from a file. 


br_uint_16 num 
The maximum number of matched actors to store at actors. 


Between BrBegin () ,, & BrEnd () ,,. Filing system available. Memory can be 
allocated. 





* Any existing file of the same name is overwritten. 
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Effects: | Searches for filename, if no path specified with file looks in current directory, if 
not found tries, in order, the directories listed in BRENDER_PATH (if defined). 


Stores a pointer to the root actor of each loaded hierarchy into the respective 
element of actors. See BrActorLoad ().; for details of how each hierarchy is 
loaded. 


Result;  br_uint_32 


The number of actor hierarchies loaded successfully. Will be between zero and 
num (inclusive). 


Remarks: | Ensure that necessary models and materials are loaded and added into the registry 
before calling this function. 


Example: 
br_actor* t_aScenes[5]; 
bruwint 32 tou32} 


t_u32=BrActorLoadMany (“MyScenes”,t_aScenes, 5) ; 


See Also: BrActorSaveMany(), BrActorLoad () os 
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br actor enum cbfn 


‘The Call-Back Function 


This type defines a function, supplied to BrActorEnum (),;, and to be called by it for an actor’s 


children. 


The typedef 


(See fwproto.h fora precise declaration) 


br_uint_32 


br_actor_enum_cbfn(br_actor*, void*) Enumerator 





Specification 


CBFnActorEnum () 


Description: 


Declaration: 


Arguments: 


Preconditions: 
Effects: 


Result: 


See Also: 


An application defined call-back function accepting an actor and an application 
supplied argument (as supplied to BrActorEnum () ,;). 


br_uint_32 BR_CALLBACK CBFnActorEnum(br_actor* a, void* arg) 
br_actor * a 

One of the child actors enumerated by BrActorEnum () ;. 

void * arg 

The argument supplied to BrActorEnum () .;. 

BRender has completed initialisation. 


Application defined. Avoid adding or removing children to the parent actor within 
this function. 


br_uint_32 
Any non-zero value will terminate the enumeration and be returned by 
BrActorEnum(),;. Return zero to continue the enumeration. 


BrActorEnum (),;, BrActorSearch () ,,. 
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br allocator 


The Structure 


This structure represents the definition of a memory allocation system or memory handler. All 
BRender’s memory allocation is provided by just three functions, which can be specified by the 
programmer. This is essential in cases where the standard C library functions, which BRender’s 
handler uses by default, are not available. Sometimes, more sophisticated behaviour is desired, or 
diagnostic features are needed. 


The typedef 


(See brmem.h for precise declaration and ordering) 


Handling Functions 


brmem_allocate_cbfn * allocate Memory allocation function 
brmem_free_cbfn * free Memory deallocation function 
brmem_inquire_cbfn * inquire Memory inquiry function 
Supplementary 

char * identifier Allocator name 
Members 

Handling Functions 


brmem_allocate_cbfn * allocate 

This is a pointer to the memory allocation function (See brmem_allocate_cbfn,,,). This is called 
by BrMemAllocate () ;;. 

brmem_free_cbfn * free 

This is a pointer to the memory deallocation function (See brmem_free_cbfn,,,). This is called by 
BrMemF ree () 5. 

brmem_inguire_cbfn * inquire 


This is a pointer to the memory inquiry function (See brmem_inquire_cbfn,,,). This is called by 
BrMemInquire () ;;. 
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Supplementary 


char * identifier 


Pointer to unique, zero terminated, character string (or NULL if not required). A string constant is 
recommended. 


Operations 


BrAllocatorSet () 


Description: Install a new set of memory allocation/deallocation functions. 


Declaration: const br_allocator* BrAllocatorSet (const br_allocator* newal 
) 


Arguments: const br_allocator * newal 
A pointer to an instance of abr_allocator,,, structure. 


Result: const br_allocator * 


Returns a pointer to the old br_allocator,,, structure. 


Copy/Assign 


Beware of copying the structure if identifier has been allocated from the heap. 


Access & Maintenance 


While the structure is the current allocator (most recently passed to BrAllocatorSet () ,o;) the 
members should not be changed. No maintenance required. 


Referencing & Lifetime 


The structure must remain valid until a new allocator is passed to BrAllocatorSet () ,,;. 


Initialisation 


The members should be set before the structure is passed to BrAllocatorSet () 0. 


Construction & Destruction 


The structure should ideally be statically constructed. 
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If constructed by ‘malloc’ ensure it is destroyed by ‘free’, i.e. the memory allocation handler that 
provided the storage should be the one to reclaim it. Be careful if macros have been used to redefine 
malloc to use BRender’s allocator. Generally, be aware of any constraints one handler may place on 
memory allocated by another handler. 


Supplementary 


The identifier may be used to determine the current handler in use. 
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br_angle 


The Integral Type 


This is BRender’s own angle representation. One complete revolution corresponds to the entire 
range of this data type, and therefore repeated rotations will ‘wrap around’correctly. Use whenever 
an angle needs to be represented. 


Also see br_scalar,,,and br_euler,,,. 


The typedef 

(See angles.h fora precise declaration) 

br_fixed_luf br_angle Angle type 
Related Functions 


Degree/Angle conversion 


br_scalar BrDegreeToRadian(br_scalar s) 


Converts s_ from angular units of degrees into radians. 


br_scalar BrRadianToDegree(br_scalar s) 


Converts s_ from angular units of radians into degrees. 


Arithmetic 

An angle may be negated. 

‘Two angles may be added and subtracted. 

An angle may be multiplied or divided by a standard integral type. 


The following trigonometric macros may be used: 





BR_SIN(a) Return Sine of br_angle,,, a asabr_scalar,,,. 

BR_COS (a) Return Cosine of br_angle,, a asa br_scalar,,). 

BR_ASIN(s) Return angle whose Sine is br_scalar,,, s, as a br_angle,,,. 
BR_ACOS(s) Return angle whose Cosine is br_scalar,,, s, as a br_angle,,;. 
BR_ATAN2 (y, x) Return angle whose Tangent is br_scalar,,, y/x, as a br_angle,,,. 


BR_ATAN2FAST(y,x) Faster, lower precision version of BR_ATAN2(y,x). 


See br_fixed_1s,,, for details of fixed point functions used by these macros. 
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Comparison 


All standard comparison operators may be applied between two angles. An angle may be compared 
with zero without conversion. 


Conversion 


From Numeric Constants 
BR_ANGLE_DEG (x) 
Converts x from a number of degrees to br_angle ,;. 


BR_ANGLE_RAD (x) 
Converts x from a number of radians to br_angle,,,. 


PI 
If not already defined, PI is defined as 3.14159265358979323846. 


From Integral Types 


To convert from integral types, use br_scalar,,, as an intermediary. 


From br_scalar,,, 
br_angle BrScalarToAngle(br_scalar s) 


Converts s_ from a fractional revolution (0..1). 
br_angle BrDegreeToAngle(br_scalar d) 
Converts d from an angle in degrees. 


br_angle BrRadianToAngle(br_scalar r) 


Converts r from an angle in radians. 


To Integral Types 


To convert to integral types, use br_scalar,,, as an intermediary. 


To br_scalar,,, 
br_scalar BrAngleToScalar (br_angle a) 
Converts a toa fractional revolution (0..1). 


br_scalar BrAngleToDegree(br_angle a) 
Converts a to an angle in degrees. 


br_scalar BrAngleToRadian(br_angle a) 
Converts a to an angle in radians. 


Copy/Assign 


Only assign zero or angles. Use conversions in all other cases. 
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br boolean 


The Integral Type 


BRender’s boolean type. Use this type where only a boolean value is intended. 


The typedef 

(See compiler.h for precise declaration) 

int br_boolean Normal type of boolean C expression 
Arithmetic 


All standard C arithmetic operators are valid as with the standard C boolean type, i.e int. 


Comparison 


All standard C comparison operators are valid as with the standard C boolean type, i.e int. 


Conversion 
From True 

BR_TRUE 

Use as a value representing boolean true. 
From False 


BR_FALSE 


Use as a value representing boolean true. 
From any integral type 


BR_BOOLEAN (exp) 


Converts exp from any integral or pointer value into a boolean value. 


Copy/Assign 


Freely assign (br_boolean to br_boolean, that is). Use wherever a boolean value is intended. 
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br bounds 


The Structure 


A data structure describing an axis-aligned bounding box for a model or hierarchy of actors. 


The typedef 


(See vector.h for precise declaration and ordering) 


br_vector3 min Minimal corner 
br_vector3 max Maximal corner 
Related Functions 

Scene Modelling 


See BrScenePick3D () x. 


Image Support 


See BrOnScreenCheck () ,.,. 


Related Structures 


Note that this structure is not used by the render bounds call-back function (it represents its bounds 
in pixel co-ordinates). 


Scene Modelling 


See br_actor,,, br_model1,,,. 


Members 


br_vector3 min 


Co-ordinates of the minimal corner of the bounding box. 


br_vector3 max 


Co-ordinates of the maximal corner of the bounding box. 
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Operations 


BrBoundsToMatrix34 () 


Description: — Find the transform that maps a 2 unit cube centred at the origin to the given 
bounding box. 


Declaration: br_matrix34* BrBoundsToMatrix34 (br_matrix34* mat, 
const br_bounds* bounds) 


Arguments: br_matrix34 * mat 


Anon-NULL pointer to the destination matrix, into which will be placed the 
transform. 


const br_bounds * bounds 
Anon-NULL pointer to the bounding box. 


Effects:  Willcalculate the transform required to transform a 2 unit cube centred at the origin 
to the given bounding box. 


Result! br_matrix34 * 
The pointer to the destination matrix, mat, returned for convenience. 


Remarks: — Typically used to facilitate 3D cursors, e.g. a child model actor with a cursor model 
whose co-ordinates are based upon a 2 unit cube, can use this function to define its 
transform. 


See Also: br_actor,, 


Copy/Assign 


Copy by assignment. 


Initialisation 


Use vector initialisers, e.g. 


br_bounds my_bounds={BR_VECTOR3(-1.,-2.,-3.), 
BR_VECTOR3 (1.,2.,3.)}; 
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br camera 


The Structure 


BRender’s camera data structure. See Camera Actors. 


The typedef 


(See camera.h for precise declaration and ordering) 


Behaviour 

br_uint_8 type Camera type 
Parameters 

br_angle field_of_view Field of view 

br_scalar hither_z Front of view volume 
br_scalar yon_z Back of view volume 
br_scalar aspect Aspect ratio («/y) 
br_scalar width Width of projection surface 
br_scalar height Height of projection surface 
Supplementary 

char * identifier Camera name 

void * user User data (application dependent) 
Related Functions 


Image Support 


See also BrActorToScreenMat rix4 () ,,, BeMatrix4Perspective () 5. 


Related Structures 


Scene Modelling 


See br_actor,,. 
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Members 
Behaviour 


br_uint_8 type 
Type of camera. Which can be one of the following: 


Camera type Behaviour 


BR_CAMERA_PARALLEL A parallel camera. Object size is independent of 


its distance from the camera. 


BR_CAMERA_PERSPECTIVE A standard perspective camera. 





Parameters 


br_angle field_of_view 


Field of view, i.e. the angle subtended at the camera between the top and bottom of the view volume 
(pyramid). Applies only to perspective cameras. The value should be greater than zero and less than 
180°. Note than this is the full angle, i.e. not the half angle, between the view z axis and top (or 
bottom) of view volume. 


br_scalar hither_z 


Distance of front of view volume from camera along negative z axis, i.e. -hither_z in view co- 
ordinates. The value should be greater than zero. 


be. SCalar vorn.Z 


Distance of back of view volume from camera along negative z axis, i.e.-yon_z in view co-ordinates. 
The value should be greater than hither_z. 


br_scalar aspect 


Scaling factor for width of viewing volume. For perspective cameras, +1 in y view ordinates is mapped 
to the height of the output pixel map, and taspect in x view ordinates is mapped to the width of 
the output pixel map. For parallel cameras, the height of the view volume is mapped to the height 
of the output pixel map, whereas widthxaspect is mapped to the width of the output pixel map. 
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Correct Aspect 


If you want to maintain correctly proportioned images on a screen, then the ratio between the sides 
of the physical image should be the same as that of the view volume. Therefore, for perspective 
cameras, aspect should be calculated as the ratio between the physical dimensions of the output 


pixel map, i.e. its physical width divided by its physical height (both of which may be computed 
directly in terms of pixel map resolution if pixels are square). For parallel cameras, aspect would 
have to be defined such that widthxXaspect+height is the same as the ratio between the 
physical dimensions of the output pixel map — this is effectively modifying the width of the view 
volume to neatly fit the pixel map. In this case, aspect is relatively redundant as it might as well 
be left at unity with just width needing to be changed. 





br_scalar width 


Width of view volume (rectangular prism) in world co-ordinates (before aspect is applied) — the 
actual width is widthxaspect. Applies only to parallel cameras. 


br_scalar height 


Height of view volume (rectangular prism) in world co-ordinates. Applies only to parallel cameras. 
Supplementary 


char * identifier 


Pointer to unique, zero terminated, character string (or NULL if not required). 


If identifier is set by BrActorLoad (),, or BrActorLoadMany () 9) it will have been constructed 
using BrResStrDup () 4. 


void * user 


This member may be used by the application for its own purposes. It is initialised to NULL upon 
allocation (if allocated by BRender), and not accessed by BRender thereafter. 


Copy/Assign 


The camera should copied using structure assignment. 


Access & Maintenance 


Modification is not recommended during rendering, especially if applied to the viewing camera. The 
members should always accord with the camera type. The aspect may need to be updated in line with 
changing image dimensions. 
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Referencing & Lifetime 


If not constructed by BrActorAllocate(),, it may be multiply referenced (given a sufficient 
lifetime). The camera structure should be maintained at least as long as it is referenced by any actor. 


Initialisation 


Only members applicable to the camera type need be initialised. 





E.g. BrActorAllocate (BR_ACTOR_CAMERA, NULL) currently initialises a br_camera,,, 
structure as follows (after performing memset (, 0, sizeof (br_camera) )): 


br_camera* camera; 


camera->type=BR_CAMERA_ PERSPECTIVE; 
camera->field_of_view=BR_ANGLE_DEG (45); 
camera->hither_z=BR_SCALAR(0.1); 
camera->yon_z=BR_SCALAR(10.0); 
camera-—>aspect=BR_SCALAR(1.0); 


Construction & Destruction 


‘The camera structure can either be constructed/destroyed by the application, or by supplying NULL 
to BrActorAllocate () q. 


Supplementary 


Cameras created by BrActorAllocate(),, are allocated from the BR_MEMORY_CAMERA 
(“CAMERA”) resource class, and hence can benefit from the resource class supplementary functions. 





Import & Export 


Cameras are imported and exported with actors that specify them. See BrActorLoad () .; and 
BrActorSave () 4. 
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br colour 


The Integral Type 


BRender’s native 32 bit colour representation. Red, Green and Blue each have 8 bits, leaving a further 
8 bits for an optional alpha value (typically representing opacity). 


Blue occupies bits 0 to 7, Green occupies bits 8 to 15, Red occupies bits 16 to 23, and Alpha occupies 
bits 24 to 31. 


Note that in some situations, a colour of zero is considered transparent (See br_material,,, and 
br_pixelmap,,,). 


The typedef 


(See colour. h for precise declaration and ordering) 
unsigned long int br_colour Packed RGBA values 


Arithmetic 


Binary operations (And &, Or |, Not ~, XOr *) may sometimes be useful. However, all operands 
should still be colours, and if necessary, constructed using BR_COLOUR_RGB (). 


Comparison 


Only equality comparisons are valid between colours. 


Conversion 


From individual component values 
BR_COLOUR_RGB (r,g,b) 


Returns a br_colour,,, given three 8-bit colour components. 
BR_COLOUR_RGBA(r,g,b,a) 


Returns a br_colour,,, given three 8-bit colour components and an 8-bit alpha 
component. 


To component values 
BR_RED (c) 


Returns the Red component of a colour (0..255). 
BR_GRN (c) 


Returns the Green component of a colour (0..255). 
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BR_BLU (c) 


Returns the Blue component of a colour (0..255). 
BR_ALPHA (c) 


Returns the Alpha component of a colour (0..255). 


Copy/Assign 


Only assign colours. 


Copyright © 1996 Argonaut Technologies Limited 1 1 5 








br_diag_failure_cbfn 





br diag _failure_cbfn 


‘The Call-Back Function 


This type defines a call-back function, primarily intended for the failure member of the 
br_diaghandler,,, structure. 


The typedef 


(See brdiag.h fora precise declaration) 


void 


br_diag_failure_cbfn(const char *) Handle failure and message 


Specification 


CBFnDiagFailure () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


Remarks: 


Example: 
See Also: 


116 


An application defined call-back function that is called upon a serious, unexpected 
error or failure, with a descriptive message. Remember, a release version of your 
software should never fail. 


void BR_CALLBACK CBFnDiagFailure(const char* message) 
const char * message 


Pointer to zero terminated character string describing the failure. 

The diagnostic handler has been setup (BrDiagHandlerSet () ,,,.). BRender has 
not necessarily completed initialisation. In an unknown state. A failure has 
occurred. BRender is not expecting the function to return. 


Behaviour is up to the application, but the following procedure can be taken as a 
suggestion. 


Set a failure condition flag (to detect escalation). Optionally, immediately inform 
user of failure. Re-establish a known state. Perform diagnostics of hardware and 
software, inform user of any diagnosed faults (optionally, also of original failure). 
End failure condition, and resume (do not return). 

Avoid allocating memory in your failure call-back function, or you may need special 
care in handling out-of-memory conditions. BRender’s default failure call-back 
function does not allocate memory. 

See stddiag.c for examples of diagnostic handler functions. 


CBFnDiagwWarning () ,,,. 
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br_diag warning _cbfn 


‘The Call-Back Function 


This type defines a call-back function, primarily intended for the warning member of the 
br_diaghandler,,, structure. 


The typedef 

(See brdiag.h fora precise declaration) 

void br_diag_ warning _cbfn(const char *) Handle warning and message 
Specification 


CBFnDiagWarning () 


Description: | An application defined call-back function that is called upon a non-serious, 
unexpected failure, with a message describing the warning. 


Declaration: void BR_CALLBACK CBFnDiagWarning(const char* message) 
Arguments: const char * message 
Pointer to zero terminated character string describing the warning. 


Preconditions: ‘The diagnostic handler has been setup (BrDiagHandlerSet () ,,,). BRender has 
not necessarily completed initialisation. In a recoverable state. 


Effects: | Optionally inform user of warning. Return. 


Remarks: — This function is primarily intended for debugging and testing purposes. BRender 
does not currently generate warnings. 


Example: See stddiag.c for examples of diagnostic handler functions. 
See Also: CBFnDiagFailure () ,,. 
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br _diaghandler 


The Structure 


This structure represents the definition of a diagnostic handler. All BRender’s diagnostics are 
handled by just two functions, which can be specified by the programmer. This is essential in cases 
where stdout and stderr (as used by the standard C library functions) are not available (or not 
suitable). 


The typedef 


(See brdiag.h for precise declaration and ordering) 


Handling Functions 


br_diag_warning_cbfn * warning Warning delivery function 
br_diag_failure_cbfn * failure Failure delivery function 
Supplementary 

char * identifier Diagnostic handler name 
Members 

Handling Functions 


br_diag_warning_cbfn * warning 
This is a pointer to the warning delivery function (See br_diag_warning_cbfn,,,). This is 


invoked by the warning macros (See Diagnostic Support, page 65). 


br_diag_failure_cbfn * failure 


This is a pointer to the failure delivery function (See br_diag_failure_cbfn,,,). This is invoked 
by the failure, fatal and assertion macros (See Diagnostic Support). 


Supplementary 
char * identifier 


Pointer to unique, zero terminated, character string (or NULL if not required). A string constant is 
recommended. 
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Operations 


BrDiagHandlerSet () 


Description: Install a new diagnostic handler. 
Declaration: br_diaghandler* BrDiagHandlerSet (br_diaghandler* newdh) 
Arguments: br_diaghandler * newdh 


A pointer to an instance of abr_diaghandler,,, structure (should really be 
static). If NULL the default diagnostic handler will be used (uses the standard C I/ 
O library). 


Result: br_diaghandler * 


Returns a pointer to the old diagnostic handler (possibly NULL). This may be used 
to pass diagnostics on, if desired. 


Remarks: The diagnostic handler may be specified at any suitable time. BrBegin(),) will 
specify a default diagnostic handler if no handler is currently defined. 


Note that diagnostics generated without a diagnostic handler present will only be 
caught in the debug build. 


If not BrBegin () ,, This should be the first BRender function called. 


You should cater for the circumstance arising, if in the process of handling 
diagnostics, your diagnostic handler may call functions that may themselves 
generate diagnostics. 


Copy/Assign 


Beware of copying the structure if identifier has been allocated from the heap. 


Access & Maintenance 


While the structure is the current handler (most recently passed to BrcDiagHandlerSet () ,,.) the 
members should not be changed. No maintenance required. 


Referencing & Lifetime 


The structure must remain valid at least until a new handler is passed to BrDiagHandlerSet () ,,., 
and may need to remain valid longer if a newer diagnostic handler uses it to pass diagnostics on. 


Initialisation 


The members should be set before the structure is passed to BreDiagHandlerSet () ,,». 
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Construction & Destruction 


The structure should ideally be statically constructed. 


Supplementary 


The identifier may be used to determine the current handler in use. 
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br euler 


The Structure 


Euler’ angles can be used to represent the orientation of an object. Three separate rotations are 
applied in turn, in a specific order. Euler angles can be either static or relative. With relative Euler 
angles, the rotations are performed around axes relative to the rotations already performed. With 
static Euler angles, the rotations are performed around static axes. 


The typedef 

(See angles.h for precise declaration and ordering) 

br_angle a First angle 

br_angle b Second angle 

br_angle c Third angle 

br_uint_8 order Rotation order (static/relative) 
Related Functions 

Maths 


See BrMat rix34ToEuler () »,, BrMatrix4ToEuler () ,,,, BrQuatToEuler () ,,;. 


Related Structures 


Maths 


See br_transforn,,,. 


Members 


br_angle a 


First angle of rotation. 


br_angle b 


Second angle of rotation. 


br_angle c 


Third angle of rotation. 





* Pronounced ‘oiler’ as in boiler. 
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br_uint_8 order 


The order in which the angles of rotation are applied. The following symbols define the set of values 
which may be used. The first three letters (of the suffix to BR_EULER) indicate the order in which 
rotations occur about which axes. The last letter indicates whether the rotations are static or relative. 


R_EULER_XYZ_. 
LER_XYX_ 
R_EULER_XZY_ 
R_EULER_XZX_ 
LER_YZX_ 
LER_YZY_ 
R_EULER_YXZ_. 
R_EULER_YXY_ 
LER_ZXY_ 
R_EULER_ZXZ_. 
LER_ZYX_ 
LER_ZYZ_ 
R_EULER_ZYX_ 
R_EULER_XYX__ 
R_EULER_YZX__ 
LER_XZX_ 
R_EULER_XZY__ 
LER_YZY_ 
LER_ZXY_ 
R_EULER_YXY__ 
LER_YXZ_ 
R_EULER_ZXZ__ 
LER_XYZ_ 
R_EULER_ZYZ__ 
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BR_EULER_XYZ_S is equivalent to the matrix transform: 


Ryay Ry Rae) 


BR_EULER_XZY_R is equivalent to the matrix transform: 


R 


y(c) 


See br_matrix34,,,. 


Arithmetic 


See br_transform,,,. 
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Conversion 


br_euler 


From Quaternions, Matrices and Transforms 


See BrQuatToEuler () »,, BeMatrix34ToEuler () .,, BeTransformToTransform () ;;. 


To Quaternions, Matrices and Transforms 


See BrEulerToQuat () ,,,, BcEulerToMatrix34 () ,,,,and BrEulerToMatrix4 (),,, as described 


below. 


Also see BrTransformToTransform() ,;;. 


BrEulerToQuat () 


Description: 


Declaration: 


Arguments: 


Result: 


Convert abr_euler,,, to a quaternion, that would have the same transformational 
effect. 


br_quat* BrEulerToQuat (br_quat* q, br_euler* euler) 
br_quat * q 

A pointer to the destination quaternion to receive the conversion. 
br_euler * euler 

A pointer to the source Euler angle. 

br_quat * 


Returns q for convenience. 


BrEulerToMatrix34 () 


Description: 


Declaration: 


Arguments: 


Result: 


Convert abr_euler,,, toa 3D affine matrix, that would have the same 
transformational effect. 


br_matrix34* BrEulerToMatrix34 (br_matrix34* mat, 
const br_euler* euler) 


br_matrix34 * mat 


A pointer to the destination matrix to receive the conversion. 
const br_euler * euler 

A pointer to the source Euler angle. 

br_matrix34 * 


Returns mat for convenience. 
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BrEulerToMatrix4 () 


Description: | Convertabr_euler,,, toa 3D affine matrix, that would have the same 
transformational effect. 


Declaration: br_matrix4* BrEulerToMatrix4 (br_matrix4* mat, 
const br_euler* euler) 


Arguments: br_matrix4 * mat 


A pointer to the destination matrix to receive the conversion. 


const br_euler * euler 


A pointer to the source Euler angle. 


Result! br_matrix4 * 


Returns mat for convenience. 


Remarks: Equivalent to BrEulerToMat rix34 () ,,;. 


Copy/Assign 


Copy by assignment. Freely reference. 


Initialisation 


Initialise by member (use BR_LANGLE_DEG() or BR_ANGLE_RAD ()) or structure assignment. Zero is a 
valid order. 
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br face 


The Structure 


The face data structure, describing a single triangular face. 


The typedef 

(See model.h for precise declaration and ordering) 

br_uint_16 vertices [3] Vertices around face 

br_material * material Face material 

br_uint_16 smoothing Controls smoothing between shared edges 
br_uint_8 flags Face flags 

Related Structures 


See br_model1,,, for the structure in which vertices are used. 


Members 


br_uint_16 vertices[3] 


An array of vertex indices specifying the vertices of this face. This defines a polygon of the model’s 
the surface. The order in which vertices are listed is important. The primary, visible side of a face 
from the viewpoint has its vertices listed in anticlockwise order. 


See br_model,,, and br_vertex;,,,. 


br_material material 


Pointer to the material structure associated with this face. Note that if this is NULL and the face is 
part of a model actor’s model, then the model actor’s material (as specified or inherited) will be used. 


br_uint_1l16 smoothing 


A 16 bit field in which each bit represents a smoothing group. If, when smooth-shading a surface, two 
adjacent faces share a smoothing group, the edge between them will be smooth. 


br_uint_8 flags 


Face flags, indicating whether the edges of the face abut co-planar faces, and thus do not need to be 
drawn in the wire-frame render style BR_RSTYLE_EDGES. The following table describes each flag. 
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Flag Meaning 

BR_FACEF_COPLANAR_0 The face adjoining edge 0 is co-planar with this face. 
BR_FACEF_COPLANAR_1 The face adjoining edge 1 is co-planar with this face. 
BR_FACEF_COPLANAR_2 The face adjoining edge 2 is co-planar with this face. 


Copy/Assign 


Face structures should not be copied by assignment — copy member-wise instead. Note that faces so 
copied, will still need the models that refer to them to be updated before they are involved in 
rendering. 


Access & Maintenance 


Members may be freely accessed. The structure should remain valid while it is referenced by any 
model. Some private members are modified if BeModelUpdate (),,, is applied to the model that 
references the face. Any changes to members will not affect models that use the face until 
BrModelUpdate (),,,, is called. BeModelUpdate (),,, must be called before rendering if any changes 
have been made to faces of models that are in the registry. 


Referencing & Lifetime 


Be careful of referencing faces especially ones allocated by BrModelAllocate () ,,,, they are liable 
to be moved around during BrModelUpdate () ,,,, say. Faces are generally only allocated as arrays 
completely describing a model. Always access using indexing from the model’s faces member. 


The structure should remain valid while it is referenced by any model. If constructed by 
BrModelAllocate(),,, it will be destroyed when the model it was constructed with is destroyed (or 
upon BrModelUpdate () »,, if BR_-MODF_KEEP_ORIGINAL had not been set beforehand). 


Initialisation 
If not constructed by BrModelAllocate() ,,,, ensure the structure is first zeroed, e.g using 
memset (...,0,sizeof (br_face) ). Set the members appropriately. Models that refer to such 


faces must have the flag BR_MODF_KEEP_ORIGINAL set. Models referring to initialised faces must be 
updated before they are involved in rendering. 


Construction & Destruction 


If this structure is constructed by BrModelAllocate(),,, (or indirectly by BrModelLoad () ,,,) it will 
be destroyed with the model (or upon BrModelUpdate () »,, if BR_MODF_KEEP_ORIGINAL had not 
been set beforehand). It may be constructed (and appropriately destroyed) any other way (as long as 
BR_MODF_KEEP_ORIGINAL is set in the model). 
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Supplementary 


When constructed by BrModelAllocate(),,, faces are allocated from the “FACES” memory class. 
It is probably better to organise any enumeration around models (see br_model1,,,). 





Import & Export 


Faces can be imported and exported with models. 
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br filesystem 


The Structure 


BRender routes all filing system calls through an instance of this structure. The syntax of each call- 
back function corresponds exactly with the standard C library calls. This allows the user to tailor 
BRender’s file system characteristics to suit any platform. 


See BrFilesystemSet () ,,. for details of how to specify a particular filing system handler. 


The typedef 


(See brfile.h for precise declaration and ordering) 


Informational 


brfile_attributes_cbfn * attributesFunction to inquire capabilities of filing system 


Filing functions 


brfile_open_read_cbfn * open_read 
brfile_open_write_cbfn *open_write 


brfile_close_cbfn * 
brfile_eof_cbfn * 
brfile_getchr_cbfn * 
brfile_putchr_cbfn * 
brfile_read_cbfn * 
brfile write_cbfn * 


brfile_getline_cbfn * 
brfile_putline_cbfn * 
brfile_advance_cbfn * 


Supplementary 


char * 


Members 


Informational 


close 
eof 
getchr 
putchr 
read 
write 
getline 
putline 
advance 


identifier 


Function to open a file for reading 
Function to open a file for writing 
Function to close an opened file 
Function to check for end of file 
Function to read one character 
Function to write one character 
Function to read a block 

Function to write a block 
Function to read a line of text 
Function to write a line of text 
Function to advance through a stream 


Name of filing system 


brfile_attributes_cbhfn *attributes 


This is a pointer to the function to obtain attributes of the filing system (see 
brfile_attributes_cbfn,,,). This is called by BrFileAttributes () ;, (See Filing System 


Support, page 57). 
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Filing Functions 


brfile_open_read_cbfn * open_read 

This is a pointer to the function to open a file for reading (see br£ile_open_read_cbfn,,,). This 
is called by BrFileOpenRead () ,. (See Filing System Support, page 57). 
brfile_open_write_cbfn * open_write 

This is a pointer to the function to open a file for writing (see brfile_open_write_cbfn,,,). This 


is called by BrFileOpenWrite () ;, (See Filing System Support, page 57). 


brfile close _cbhfn * close 


This is a pointer to the function to close a file (see br£ile_close_cbfn,,;). This is called by 
BrFileClose(),, (See Filing System Support, page 57). 


bréeile -eot chin: *.-eo0£ 
This is a pointer to the function to check for end of file (see brfile_eof_cb£n,,,). This is called 


by BrFileEof (),; (See Filing System Support, page 57). 


brfile_getchr_cbfn * getchr 


This is a pointer to the function to read one character (see brfile_getchr_cbfn,,;). This is called 
by BrFileGetChar () , (See Filing System Support, page 57). 


brftileputchr-cbhin * putchr 


This is a pointer to the function to write one character (see brfile_putchr_cbfn,,,). This is called 
by BrFilePutChar () ., (See Filing System Support, page 57). 


brfile_ read_cbfn * read 


This is a pointer to the function to read a block (see br£file_read_cbfn,,,). This is called by 
BrFileRead () ,, (See Filing System Support, page 57). 


brtilLe: weite -chin -* write 


This is a pointer to the function to write a block (see brfile_write_cbfn,,,). This is called by 
BrFileWrite()., (See Filing System Support, page 57). 
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brfile_getline_cbfn * getline 


This is a pointer to the function to read a line of text (see brf£ile_getline_cbfn,,,). This is called 
by BrFileGetLine () ,, (See Filing System Support, page 57). 


brfile_putline_cbfn * putline 


This is a pointer to the function to write a line of text (see br£ile_putline_cbfn,,,). This is called 
by BrFilePutLine () <. (See Filing System Support, page 57). 


brfile_ advance_cbfn * advance 


This is a pointer to the function to advance through a stream (see br£file_getchr_cbfn,,;). This 
is called by BrFileGetChar () , (See Filing System Support, page 57). 


Supplementary 


char * identifier 


Pointer to unique, zero terminated, character string (or NULL if not required). A string constant is 
recommended. 


Operations 


BrFilesystemSet () 


Description: Install a new file system. 


Declaration: const br _filesystem* BrFilesystemSet (const br_filesystem* ne 
wfs) 


Arguments: const br_filesystem * newfs 
A pointer to an instance of abr_filesystem,,, structure. 
Result: const br_filesystem * 


Returns a pointer to the old br_filesystem,,, structure. 


Copy/Assign 


Beware of copying the structure if identifier has been allocated from the heap. 
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Access & Maintenance 


While the structure is the current handler (most recently passed to BrFilesystemSet () ,,.) the 
members should not be changed. No maintenance required. 


Referencing & Lifetime 


The structure must remain valid until a new handler is passed to BrFilesystemSet () ,x. 


Initialisation 


The members should be set before the structure is passed to BrFilesystemSet () j. 


Construction & Destruction 


The structure should ideally be statically constructed. 


Supplementary 


The identifier may be used to determine the current handler in use. 
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br fixed [ls] [su] [f] 


The Integral Types 


These are BRender’s current fixed point types. The application programmer should never use these 
types directly. The documentation for these types is only included for completeness and is not meant 
to validate their use. The representation of fixed point values and the validity of operations upon 

them is likely to change in the future. 


The typedef 


(See fixed.h for precise declarations) 


long 
short 
unsigned long 


unsigned short 


short 
char 


br_fixed_ls 
br_fixed_lsf 
br_fixed_lu 
br_fixed_luf 
br_fixed_ss 
br_fixed_ssf 
br_fixed_su 


Fixed — Long Signed(15.16) 

Fixed — Long Signed Fraction(0. 15") 
Fixed — Long Unsigned(16.16) 

Fixed - Long Unsigned Fraction(0.16) 
Fixed — Short Signed (7.8) 

Fixed - Short Signed Fraction (0.7*) 
Fixed - Short Unsigned (8.8) 


unsigned short 


unsigned char br_fixed_suf 


Arithmetic 
Fixed point values may be negated. 
Two fixed point values of the same type may be added and subtracted. 


A fixed point value may be multiplied or divided by a standard integral type. 


Fixed - Short Unsigned Fraction(0.8) 


The following functions all accept br_fixed_1s,,, arguments (except where otherwise stated). 


br_fixed_ls 


br_fixed_ls 


br_fixed_ls 
br_fixed_ls 


br_fixed_ls 
br_fixed_ls 


br_fixed_ls 


BrFixedAbs (br_fixed_ls a) 


Return the equivalent of abs (a). 


BrFixedMul (br_fixed_ls a, br_fixed_ls b) 


Return the equivalent of a*b. 


BrFixedMac2 (br_fixed_ls a, br_fixed_ls b, br_fixed_ls c, 


Return the equivalent of a*b + c*d. 


BrFixedMac3 (br_fixed_ls a, br_fixed_ls b, br_fixed_ls c, 
d,br_fixed_ls e, br_fixed_ls f) 


Return the equivalent of a*b + c*d + e*f. 


BrFixedMac4 (br_fixed_ls a, br_fixed_ls b, br_fixed_ls c, 





* Note that signed fractions have one fewer bit than the fractional component of their non-fractional counterparts 
to make way for the sign bit. 
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br_fixed_ls 


br_fixed_ls 


br_fixed_ls 


br_fixed_ls 
br_fixed_ls 


br_fixed_ls 


br_fixed_ls 


br_fixed_ls 
br_fixed_ls 


br_fixed_ls 


br_fixed_ls 


br_fixed_ls 
br_fixed_ls 


br_fixed_ls 


br_fixed_ls 


br_fixed_ls 


br_fixed_ls 


br_fixed_ls 
br_fixed_ls 


br_fixed_ls 
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d,br_fixed_ls e, br_fixed_ls f, br_fixed_ls g, br_fixed_ls h) 


Return the equivalent ofa*b + c*d + e*f + g*h. 
BrFixedSqr (br_fixed_ls a) 
Return the equivalent of a*a. 


BrFixedSqr2 (br_fixed_ls a, br_fixed_ls b) 
+ b*b. 


br_fixed_ls b, br_fixed_ls c) 


Return the equivalent of a*a 
BrFixedSqr3 (br_fixed_ls a, 
# DAD tk Ere, 


br_fixed_ls b, br_fixed_ls c, 


Return the equivalent of a*a 
BrFixedSqr4 (br_fixed_ls a, 
dq) 

+ bo * bt -C* Codd. 


br_fixed_ls b) 


Return the equivalent of a*a 
BrFixedLength2 (br_fixed_ls a, 


Return the equivalent of sqrt (a*a + b*b) 
BrFixedLength3 (br_fixed_ls a, br_fixed_ls b, br_fixed_ls c) 


Return the equivalent of sqrt (a*a + b*b + c¥*c). 
BrFixedLength4 (br_fixed_ls a, br_fixed_ls b, br_fixed_ls c, 
d) 

Return the equivalent of sqrt (a*a + b*b + c*c + d*d). 
BrFixedRLength2 (br_fixed_ls a, br_fixed_ls b) 


Return the equivalent of 1/sqrt (a*a + b*b) (low precision). 
BrFixedRLength3 (br_fixed_ls a, br_fixed_ls b, br_fixed_ls c) 


Return the equivalent of 1/sqrt (a*a + b*b + c*c) (low precision). 


BrFixedRLength4 (br_fixed_ls a, br_fixed_ls b, br_fixed_ls c, 
d) 
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Return the equivalent of 1/sqrt (a*a + b*b + c*c + d*d) (low precision). 


BrFixedDiv (br_fixed_ls a, br_fixed_ls b) 


Return the equivalent of a/b 
BrFixedDivF (br_fixed_ls a, br_fixed_ls b) 
we 2AS A 
br_fixed_ls b) 


Return the equivalent of a/b 
BrFixedDivR (br_fixed_ls a, 


(rounded towards zero). 
br _fixed_ls b, br_fixed_ls c) 


Return the equivalent of a/b 
BrFixedMulDiv (br_fixed_ls a, 


Return the equivalent of a*b/c. 


BrFixedMac2Div (br_fixed_ls a, 
d,br_fixed_l1s e) 


br_fixed_ls b, br_fixed_ls c, 


Return the equivalent of (a*b + c*d)/e. 
BrFixedMac3Div(br_fixed_ls a, br_fixed_ls b, br_fixed_ls c, 
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br_fixed_ls 
br_fixed_ls 
br_fixed_ls 


br_fixed_ls 


br_fixed_ls 
br_fixed_ls 


br_fixed_ls 
br_fixed_ls 


br_fixed_ls 
br_fixed_ls 


br_fixed_ls 


br_fixed_ls 


br_angle 


br_angle 


br_angle 


br_angle 


br_fixed_ls 


br_fixed_ls 
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£] 


d,br_fixed_ls e, br_fixed_ls f, br_fixed_ls g) 


Return the equivalent of (a*b + c*d + e*f)/g. 
BrFixedMac4Div(br_fixed_ls a, br_fixed_ls b, br_fixed_ls c, 
d,br_fixed_ls e, br_fixed_ls f, br_fixed_ls g, br_fixed_ls h, 
i) 

Return the equivalent of (a*b + c*d + e*f + g*h)/i. 

BrFixedRcp (br_fixed_ls a) 


Return the equivalent of 1.0/a. 


BrFixedFMac2 (br_fixed_lsf a, 
d) 


br_fixed_ls b, br_fixed_lsf c, 


Return the equivalent of a*b + c*d (a &c are fractions). 

BrFixedFMac3 (br_fixed_lsf a, br_fixed_ls b, br_fixed_lsf c, 
d,br_fixed_lsf e, br_fixed_ls f) 

Return the equivalent of a*b + c*d + e*f (a,c &e are fractions). 
BrFixedFMac4 (br_fixed_ls a, br_fixed_ls b, br_fixed_ls c, 
d,br_fixed_ls e, br_fixed_ls f, br_fixed_ls g, br_fixed_l1s h) 

Return the equivalent of a*b + c*d + e*f + g*h (a,c,e,&g are fractions). 


BrFixedSin(br_angle a) 


Return the equivalent of sin(a) (see br_angle,,,). 


BrFixedCos (br_angle a) 


Return the equivalent of cos (a) (see br_angle,,,). 


BrFixedASin (br_fixed_ls s) 


Return the equivalent of asin(s) (see br_angle,,;). 


BrFixedACos (br_fixed_ls c) 


Return the equivalent of acos (c) (see br_angle,;). 


BrFixedATan2 (br_fixed_ls x, br_fixed_ls y) 


Return the equivalent of atan2 (x,y) (see br_angle,,;). 


BrFixedATan2Fast (br_fixed_ls x, br_fixed_ls y) 


Return the equivalent of atan2(a) (low precision) (see br_angle,,;). 
BrFixedSqrt (br_fixed_ls a) 

Return the equivalent of sqrt (a). 
BrFixedPow(br_fixed_ls a, br_fixed_ls b) 


Return the equivalent of pow(a,b). 


Comparison 


All standard comparison operators may be applied between the same types. Comparison with zero is 


also valid for all types. 
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Conversion 


From 1 


The following macros evaluate to unity in each type, e.g. BR_ONE_LS may be cast tobr_fixed_ls,,, 
and represents unity for that type. However, note that for fractional types, unity can not be stored; 
the macro is intended for use as a factor. 

BR_ONE_LS 

BR_ONE_LSF 

BR_ONE_LU 

BR_ONE_LUF 

BR_ONE_SS 

BR_ONE_SSF 

BR_ONE_SU 

BR_ONE_SUF 











From integral types 
BriIntToFixed (i) 


Converts i froma short orunsigned short toa value suitable to cast to 
br_fixed_ls,,, or br_fixed_1u,,, respectively. 


BrFloatToFixed(f) 


Converts £ from an floating point value to a value of type br_scalar,,, (itself 
br_fixed_l1s,,,) 


From Other BRender Types 


br_fixed_ls BrScalarToFixed(br_scalar s) 


Converts s_ from scalar type to fixed type. 


To integral types 
BrFixedToInt (i) 


Converts i from a value of type br_fixed_1s,,, or br_fixed_1u,,, toa value 
suitable to cast toa short orunsigned short respectively. 


BrFixedToFloat(s) 


Converts s from a value of type br_fixed_1s,,, or br_fixed_1u,,, toa value 
suitable to cast toa float. 


To Other BRender Types 


br_scalar BrFixedToScalar (br_fixed_ls f) 


Converts £ from fixed type to scalar type. 
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Copy/Assign 


Only assign zero, though Fractions may be assigned to non-Fractions of the same type, e.g. ‘lsf to 


‘1s. Use conversions in all other cases. 
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br font 


The Structure 


The font data structure, describing a BRender font. Up to 223 bit mapped characters are supported. 
The font does not necessarily need to accord with ASCII character codes, however the non-printing 
ASCII codes (0-31 & 127) of the 256 codes possible are reserved for such a purpose. 


Three ASCII fonts (covering codes 32-126) are predefined by BRender: 
BrFontFixed3x5 3 pixels wide by 5 high, fixed pitch font 
BrFontProp4x6 4 pixels wide by 6 high, pixel proportional font 
BrFontProp7x9 _ 7 pixels wide by 9 high, pixel proportional font 








The typedef 

(See brfont.h for precise declaration and ordering) 

br_uint_32 flags Properties of the font 

br_uint_16 glyph_x Pixel width of fixed pitch characters 
br_uint_16 glyph_y Pixel height of characters 

br_int_16 spacing_x Horizontal pixel spacing of characters 
br_int_16 spacing_y Vertical pixel spacing of characters 
br_int_8 * width Pixel widths of proportional characters 
br_uint_16 * encoding Offsets to data for each character 
br_uint_8 * glyphs Pointer to bit mapped character data 
Related Functions 


See BrPixelmapText () ,,,, BcPixelmapTextF (),,,, BcPixelmapTextWidth () »,,, 
BrPixelmapTextHeight () ,,;. 


Members 


br uint 32 tlags 


The flags member contains various details about the properties of the font such as whether it is 
proportional or not. 


The presence of the flag whose value is defined by the symbol BR_FONTF_PROPORTIONAL indicates 
that the spacing between characters is proportional to their widths (width is used), otherwise each 
character is regularly spaced (glyph_x is used). 

bE Une 16 “oly pit. 


The width of characters in fixed pitch fonts. Note that there is an implicit single pixel gap between 
characters. 


Copyright © 1996 Argonaut Technologies Limited 1 3 7 





br_font 


br uint—le. glyph 


The height of the font in pixels (the number of pixel rows making up the largest character). 


brant 16 spacing =x 


The width in pixels between horizontally adjacent character co-ordinates. This is not currently 
implemented by BRender, but could be used to determine the spacing between columns of text 
when interpreting ASCII HTAB say. 


br-int 1 spacaing-¥ 


The height in pixels between vertically adjacent character co-ordinates. This is not currently 
implemented by BRender, but could be used to determine the spacing of between rows of text when 


interpreting ASCII WTAB or CRLF say. 


br_int_8 * width 


Pointer to an array of 256 widths in pixels of each character (in proportional fonts). Values for ASCII 
control codes (0-31 & 127) have reserved meanings. Note that there is an implicit single pixel gap 
between characters. 


br_uint_16 * encoding 


Pointer to an array of 256 offsets to each character’s bit map (values for ASCII control codes (0-31 & 
127) have reserved meanings), with a set bit indicating character foreground colour, and a cleared bit 
indicating transparent. 


Each character is formed of a number of rows of bytes. The number of rows in each character is equal 
to glyph_y. The number of bytes in each row is given by the integer formula below, where Width is 
the pixel width of the character (glyph_x in the case of fixed pitch fonts and width [char] in the 
case of proportional fonts). 


Width +7 
8 


Therefore, in proportional fonts, it is possible that some characters will have a different number of 
bytes per row. 


Number of bytes in each row = 


The character’s pixels are arranged in memory such that the character’s top left hand corner occupies 
the most significant bit of the first byte. Naturally a character row may use fewer pixels than all of the 
bits of the bytes it occupies, in such a case the least significant bits of the last byte of each row will 
be unused. For example, say the ASCII letter ‘E’ was stored ina font called my_font asa 10x18 
character. It would be stored in 18 pairs of bytes (36 bytes) at an address pointed to by 
my_font.glyphst+my_font.encoding[’E’]. The first byte would contain the pixels for the left 
hand 8 dots of the top row. The second byte’s two most significant bits would contain the remaining 
two dots of the top row. Subsequent bytes would contain pixels for lower rows in a similar fashion. 
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br int 3. -* glyphs 


Pointer to raw font data containing bit maps for each character. In proportional fonts the first byte 
should not be used for character data so that an encoding offset of zero can be considered NULL. 
For the same purpose, in fixed pitch fonts, there should be a dummy character definition at an 
encoding offset of zero. Note that the space character should not use this definition, but have its 
own (therefore at a non-zero offset’). 


Copy/Assign 


May be freely copied. However, be careful of a structure assignment if the lifetime of the original font 
data is unknown. 


Given that font data can be arranged in a convoluted manner, there is not necessarily a single most 
efficient way of copying it. One way to copy font data is to first determine the extent of the data by 
scanning the list of offsets and obtaining the maximum extent of each character’s data (including the 
character’s width). Another way is to copy font data character by character. 


Access & Maintenance 


The font and its data are not guaranteed to be writable, but otherwise members may be freely 
accessed (although this should be avoided during text operations). Do not modify the supplied fonts 
(though their data may be copied and subsequently modified if desired). 


Referencing & Lifetime 


The font should be maintained while references to it exist. 


Initialisation 


Initialise the entire structure to zero (using memset (, 0, sizeof (br_font) ), say) and ensure all 
the above members are set appropriately. The elements of width and encoding corresponding to 
ASCII control codes (0-31 & 127) should be set to zero. All of the remaining 223 elements must have 
valid values. Character data can be stored in any order, may overlap and need not be contiguous. In 
proportional fonts, codes for which no character is defined should have a width of zero and a zero 
encoding offset. In fixed pitch fonts, codes for which no character is defined should have a zero 
encoding offset (therefore a dummy character definition is required at an offset of zero). 


Import & Export 


There are no specific font load/save functions. See Filing System Support for details of BRender 
functions that could be used to assist font import and export. 


Do not be beguiled by the apparent simplicity of storing fonts within monochrome pixel maps. There 
are a few points at which this idea has difficulties. For instance, a monochrome pixel map may require 





* Given that overlap is permitted, only the first byte is ‘wasted’ as the space definition can have an offset of 1. 
pis p y 'y 
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4 byte alignment of pixel rows, whereas a font requires single byte alignment. Also, with proportional 
fonts, characters may not necessarily all have the same number of bytes per row, so it may not be 
possible to fit them all into a neat column. 
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br fraction 


The Integral Type 


The br_fraction,,, type can be used to represent numbers in the range [-1,+1)". Although used 
internally, this type is not currently used by the BRender API. 


Under the floating point library, br_fraction,,, isa float. Under the fixed point library, 
br_fraction,,, is a 16 bit signed fixed point number. 


The typedef 

(See scalar.h for precise declaration) 

float br_fraction Floating point Signed Fraction 
br_fixed_lsf br_fraction Fixed — Long Signed Fraction(0.15) 
Arithmetic 


No standard operators are supported. Moreover, there are few macros that directly support fractional 
arithmetic. Convert to br_scalar,,, and use that type’s arithmetic macros instead. 


The following macros are provided to assist with fractional vector arithmetic (see br_fraction,,,). 
In the following macros, arguments a, c,e and g are of type br_fraction,,,,b,d,£ andh are of 
type br_scalar,,,. The macro computes a br_scalar,,, result. 


BR_FMAC2 (a,b,c,d) 


Return the equivalentofa * b+c%*d. 
BR_FMAC3 (a,b,c,d,e, £) 


Return the equivalentofa * b+c*d+ter*f. 
BR_FMAC4 (a,b,c,d,e,f,g,h) 


Return the equivalentofa * b+c*d+e*ftg*h. 


Comparison 


Equality and comparison with zero are valid. Other standard comparison operators may be 
implemented by macros in future versions, but are currently valid. 


Conversion 


From Numeric Constants 
BR_FRACTION (x) 


Convert x from any numeric constant to br_fraction,,,. 


* Maximum value is thus BR_ONE_LS-BR_SCALAR_EPSILON (in the fixed point library). 
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BR_SCALAR_EPSILON 


Smallest positive fractional value. 


From Integral Types 


To convert from integral types, use br_scalar,,, as an intermediary. 


From br_scalar,,, 
br_fraction BrScalarToFraction(br_scalar s) 


Converts s from br_scalar,, tobr_fraction,,,. It is up to the application to 
ensure the value is in the required range. 


To Integral Types 


To convert to integral types, use br_scalar,,, as an intermediary. 


Tobr_scalar,,, 
br_scalar BrFractionToScalar(br_fraction f) 


Converts s from br_fraction,,, to br_scalar,,,. It is up to the application to 
ensure the value is in the required range. 


Copy/Assign 


Only assign zero, or fractions. Use conversions in all other cases. 
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br fvector2 


The Structure 


This is the two ordinate, fractional vector structure. It is not recommended for use, and is only 
documented here for completeness. 


The typedef 

(See vector.h for precise declaration and ordering) 

br_fraction v[2] Ordinates (O=x, 1=y) 
Members 


br_tTracti1 on: v7 (2) 


First and second ordinate. Conventionally, the first ordinate is the x axis component, and the second, 
the y axis component. 


Arithmetic 


No approved arithmetic. 


Copy/Assign 


No approved assignment. 
Initialisation 


The following macro may be used as a static initialiser. 
BR_FVECTOR2 (a,b) 


Macro expands to {BR_FRACTION (a) , BR_FRACTION(b) }. 


All other initialisation should use member-wise initialisers. 
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br fvector3 


The Structure 


This is the three ordinate fractional vector structure, typically used for storing surface normals. It is 
not intended for use by the application and is documented here only for completeness. 


The typedef 


(See vector.h for precise declaration and ordering) 
br_fraction v[3] Ordinates (0=x, 1=y, 2=3) 


Related Structures 


See br_vector3 3,7. 


This structure is currently used by br_vertex;,,, and br_face,,;. It’s presence must not be relied 
upon. 


Members 


br_ fraction v[3] 


First, second and third ordinate. Conventionally, the first ordinate is the x-axis component, the 
second, the y axis component, and the third, the z axis component. 


Arithmetic 


No approved arithmetic. 


Copy/Assign 


No approved assignment. 


Initialisation 


The following macro may be used as a static initialiser. 


BR_FVECTOR3 (a,b,c) 


Macro expands to {BR_FRACTION(a), BR_FRACTION(b), BR_FRACTION(c)}. 


All other initialisation should use member-wise initialisers. 


1 4 4 Copyright © 1996 Argonaut Technologies Limited 


br_fvector4 


br fvector4 


The Structure 


This is the four ordinate fractional vector structure. It is not intended for use by the application and 
is documented here only for completeness. 


The typedef 

(See vector.h for precise declaration and ordering) 

br_fraction v[4] Ordinates (O=x, 1=y, 2=3, 3=w) 
Related Structures 


See br_vector4,,,. 


Members 


br-fraction. v [4] 


First, second, third, and fourth ordinate. 


Arithmetic 


No approved arithmetic. 


Copy/Assign 


No approved assignment. 


Initialisation 


The following macro may be used as a static initialiser. 


BR_FVECTOR4 (a,b,c,d) 


Macro expands to {BR_FRACTION(a), BR_FRACTION(b), BR_FRACTION(c), 
BR_FRACTION(d)}. 


All other initialisation should use member-wise initialisers. 


Copyright © 1996 Argonaut Technologies Limited 1 4 5 


br_int_8/16/32 


br_ int 8/16/32 


The Integral Type 


BRender’s signed integer types. Use this type where the integer word length is critical. 


The typedef 


(See compiler.h for precise declaration) 


signed char br_int_8 8 bit signed integer 
signed short br_int_16 16 bit signed integer 
signed long br_int_32 32 bit signed integer 
Arithmetic 


All standard C arithmetic operators are valid as with standard integer types. 


Comparison 


All standard C comparison operators are valid as with standard integer types. 


Conversion 


Use casts as with any other standard C type. 


Copy/Assign 


Freely assign. Use as a standard C type, as this type is only concerned with ensuring specific sizes — 
not representation. 
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br_ light 


The Structure 


This structure is used to specify the properties of light actors. See Light Actors. 


The typedef 


(See light.h for precise declaration and ordering) 


Behaviour 

br_uint_8 type Light type 

br_colour colour Light colour 

Attenuation 

br_scalar attenuation_c Light intensity 

br_scalar attenuation_1 Linear attenuation factor for point and spot lights 

br_scalar attenuation_q Quadratic attenuation factor for point and spot lights 

Spot Lighting 

br_angle cone_inner The angle giving the cone of full-intensity light cast by a 
spot 

br_angle cone_outer The angle giving the cone of illumination of a spot 

Supplementary 

char * identifier Light name 

void * user User data (application dependent) 

Related Functions 

Scene Modelling 


See BrLightEnable (),,, and BrLightDisable () ,.. 
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Members 
Behaviour 


br_uint_8 type 


This member defines the type of the light. Note that different light types can affect rendering 
performance in different ways. Pre-lighting textures is the fastest means of lighting objects in a scene, 
ambient lighting comes next, then the three active lighting methods: direct, point and spot lights (in 
order of increasing processing requirements). The more lights in a scene’, the more computation 
required. 


The three active light types are described in the following table: 


Light Type Behaviour 
Symbol 


BR_LIGHT_DIRECT |A directed light source. The light is infinitely distant and shines along the negative z axis of the 
light actor. 


BR_LIGHT_POINT A point light source, radiating in all directions. 
BR_LIGHT_SPOT A spot light, with both spatial location and direction. A spot light has a cone of illumination and 





shines along the negative z axis of the light actor. 


The type member also encodes a flag value BR_LIGHT_VIEW which can be combined with any of the 
three light types using the ‘inclusive-or’ operation.When the flag is present, lighting calculations are 
performed in view space rather than model space. This is slower, but prevents odd anomalies if non- 
uniform scalings are used on models. 


The bit mask value BR_LIGHT_TYPE can be used to extract the light type using the ‘and’ operation. 


br colour colour 


If the rendering engine supports it, a light may be of a specific colour. Typically supported when 
rendering in ‘true colour’. 


Attenuation 


The linear and quadratic attenuation factors determine the degree by which light intensity falls off 
with respect to distance and squared distance from the light source. If dis distance, and A,, A;, A, are 
the constant, linear and quadratic attenuation factors, then light intensity L is given by: 


1 
L «x ——______., 
A,+A;d+A,d 


Ifa light actor is created with a default specification, the default values supplied for A,, A, A, are 1.0, 
0.0 and 0.0 respectively. 





* The maximum number of enabled light actors in a scene is defined by the symbol BR MAX_LIGHTS. 
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br scalar attenuation_c 


Constant attenuation component. Light intensity is inversely proportional to this value. 


br_ scalar attenuation_l 


Linear attenuation factor. Light intensity is inversely proportional to distance factored by this value. 
It only applies to point and spot lights. 


br_scalar attenuation_q 


Quadratic attenuation factor. Light intensity is inversely proportional to distance factored by the 
square of this value. It only applies to point and spot lights. 


Spot Lighting 


Spot lights are defined in terms of an inner, fully lit cone of light and an outer, penumbral cone of 
light diminishing from fully lit to unlit. The intensity fall off between the inner and outer cones is 
linear. 


The effect of having the outer cone angle smaller than the inner cone angle is undefined. 


br_angle cone_inner 


The inner cone of a spot light is defined by the angle between the cone’s axis and its circumference. 
This represents the region within which surfaces will be fully lit (subject to attenuation). 


br_angle cone_outer 

The outer cone of a spot light is defined by the angle between the cone’s axis and its circumference. 
This represents the region within which surfaces will be partially lit (subject to attenuation). The 
light level falls off linearly from the fully lit level at the inner cone to zero at the limit of the outer 
cone. 

Supplementary 

Char * 1denteiiier 


Pointer to unique, zero terminated, character string (or NULL if not required). 


If identifier is set by BrActorLoad (),, or BrActorLoadMany ()., it will have been constructed 
using BrResStrDup () 4». 


void * user 


This member may be used by the application for its own purposes. It is initialised to NULL upon 
allocation (if allocated by BRender), and not accessed by BRender thereafter. 
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Copy/Assign 


The light may be freely copied. 


Access & Maintenance 


Lights can be modified at any time, though changes will not have any effect unless the light is 
enabled (see BrLightEnable() ,,). The members should always accord with the light type. 


Referencing & Lifetime 


If not constructed by BrActorAllocate(),, it may be multiply referenced (given a sufficient 
lifetime). The light structure should be maintained at least as long as it is referenced by any actor. 


Initialisation 

Only members applicable to the light type need be initialised. 

E.g. BrActorAllocate (BR_ACTOR_LIGHT, NULL) currently initialises a br_light,,, structure 
as follows (after performing memset (,0, sizeof (br_light) )): 


br_light* light; 


light->type=BR_LIGHT_DIRECT; 
light->colour=BR_COLOUR_RGB (255,255,255); 
light->attenuation_c=BR_SCALAR(1.0); 


Construction & Destruction 


The light structure can either be constructed/destroyed by the application, or by supplying NULL to 
BrActorAllocate () y). 


Supplementary 


Lights created by BrActorAllocate(),, are allocated from the BR_MEMORY_LIGHT (“LIGHT”) 
resource class, and hence can benefit from the resource class supplementary functions. 


Import & Export 


Lights are imported and exported with actors that specify them. See BrActorLoad () 4, and 
BrActorSave () v. 
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Platform Specific 


Some platforms directly support some types of light in hardware, though there is often a significant 
limit upon how many lights of each type are supported (also see BR_MAX_LIGHTS). 
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br_map_enum_cbfn 


‘The Call-Back Function 


This type defines a function, supplied to BeMapEnum () ,,,, and to be called by it for a selection of 


maps. 


The typedef 


(See fwproto.h fora precise declaration) 


br_uint_32 


br_map_enum_cbfn (br_pixelmap*, void*) Enumerator 





Specification 


CBFnMapEnunm () 


Description: 
Declaration: 


Arguments: 


Preconditions: 
Effects: 
Result: 


See Also: 


152 


An application defined call-back function accepting a pixel map and an application 
supplied argument (as supplied to BeMapEnum () »,). 


br_uint_32 BR_CALLBACK CBFnMapEnum(br_pixelmap* map, 
void* arg) 

br_pixelmap * map 

One of the maps selected by BrMapEnun () ,,,. 

void * arg 

The argument supplied to BrMapEnum () 5,. 

BRender has completed initialisation. 

Application defined. Avoid adding or removing maps within this function. 
br_uint_32 

Any non-zero value will terminate the enumeration and be returned by 
BrMapEnum () ,,. Return zero to continue the enumeration. 


BrMapEnum () »,, BeMapF ind () 5»;. 
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br_map_find_cbfn 


‘The Call-Back Function 


This type defines a function, registered with BrMapFindHook () ,.;, to be called when 


BrMapF ind (),,; or BrMapFindMany () ,,; fail to find any map. 


The typedef 


(See fwproto.h fora precise declaration) 


br_pixelmap* 


br_map_find_cbfn(const char*) Find (when BrMapFind () fails) 


Specification 


CBFnMapF ind () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 
Result: 


Remarks: 


See Also: 


An application defined call-back function used when BrMapF ind () 5; or 
BrMapFindMany () 5; fail. 


br_pixelmap* BR_CALLBACK CBFnMapFind(const char* name) 

const char * name 

The search pattern supplied to BrMapFind () ,.; or BeMapFindMany () ,.; that did 
not match any map. 

BRender has completed initialisation. No map has an identifier that successfully 
matches the search pattern. 

Application defined. 

br_pixelmap * 

Either return an existing map that is deemed appropriate for the search pattern, or 


NULL if there isn’t one. This value will be returned by BrMapFind () ,; or 
BrMapF indMany () »;. 


This could either be used to supply a default map or to create a map. If maps were 
created on demand, then this function could search another list of available maps 

(but not yet created) and see if the pattern matched any of them, if it did, one of 

them could be registered and returned. Note that there is no way to supply more 

than one map. 


BrMapF ind () ,.,, BeMapFindMany () ,,;, BeMapF indHook () ,,;, 
BrMapF indFailedLoad () 55. 
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br material 


The Structure 


A structure describing the appearance of a material that can be applied to a surface. 


The typedef 


(See material.h for precise declaration and ordering) 


Behaviour 
br_uint_32 


Lighting 
br_ufraction 
br_ufraction 
br_ufraction 
br_scalar 


Colour 
br_colour 
br_uint_8 
br_uint_8 
br_pixelmap * 
br_pixelmap * 


flags 


ka 
kd 
ks 
power 


colour 
index_base 
index_range 
index_shade 
index_blend 


Flags determining how this material is rendered 


The ambient lighting contribution 

The directional lighting contribution 

The specular lighting contribution 

Specular power — the ‘spread’ of a specular highlight 


Material colour, when rendering in ‘true’ colour 

The unlit index (or row of a shade table) 

The range to the fully lit index (or row of a shade table) 
A shade table (for indexed textures only) 

A blend table (for indexed textures only) 


‘Texture 

br_pixelmap * colour_map An optional pixel map based texture 
br_matrix23 map_transform Transform to apply to texture map 
Supplementary 

char * identifier Material name 

void * user User data (application dependent) 
Related Functions 

Scene Modelling 


See BrEnvironmentSet () ,,, BeModelApplyMap () ,,,, BeModelFitMap () »,:. 


Scene Rendering 


See BrZbModelRender () ;;. 
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Related Structures 


Scene Modelling 


br_material 


See br_actor,,, br_model,,,, br_face,,,, br_vertex,,,. 


Scene Rendering 


See br_renderbounds_cbfn,,,, br_model_custom_cbfn,,.. 


Members 


Behaviour 


bruint— 32 thags 


This member determines how faces using the material are rendered, in terms of other members and 


aspects of the scene. 


Flag Symbol 
BR_MATF_LIGHT 
BR_MATF_PRELIT 


BR_MATF_SMOOTH 


BR_MATF_DITHER 


BR_MATF_ENVIRONMENT_I 


BR_MATF_ENVIRONMENT_L 


BR_MATF_PERSPECTIVE 














BR_MATF_DECAL 


BR_MATF_BLEND 
BR_MATF_ALWAYS_VISIBLE 


BR_MATF_TWO_SIDED 
BR_MATF_FORCE_FRONT 


Behaviour 

The material is lit — affected by lights in the scene 

The material is pre-lit — colours are taken directly from models’ vertex structures (see 
br_vertex,,,). Any lights are ignored. 

Any lighting is applied using Gouraud shading. Lighting levels are linearly interpolated 
between vertices. Otherwise, the same lighting level is used across the face 
Effectively applies a filter to the texture map to soften transitions between texels — most 
noticeable when a texel covers several screen pixels. A carefully chosen noise 
component is added to the u,v texel co-ordinates (a comparable effect to bilinear 
interpolation). Note that transparent pixels will also be dithered. 

Texels are calculated by casting a ray from the viewpoint (extended to infinity) and 
reflecting it off the face, out to an enclosing sphere (onto which the supplied texture has 
been mapped) 

Texels are calculated by casting a ray from the (local) viewpoint and reflecting it off the 
face, out to an enclosing sphere (onto which the supplied texture has been mapped) 
The texture is rendered with correct perspective (as opposed to using linear 
interpolation) 

Both the texture mapped and non-texture mapped materials are drawn, the non-texture 
mapped material only appearing beneath what would have been transparent elements 
of the texture map. 

For example, this could be used to add symbols or logos to a smooth shaded model 
The blend table is utilised (only for indexed textures) (see index_blend) 

Faces using the material will always be visible, and so back-face culling need not be 
performed for such faces 


The material has two sides, and lighting calculations are performed for both of them 


The material is forced to be in front of all other materials 
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The effects of various combinations of the first three flags are not particularly obvious so are 
described in the following table. The Texture column indicates whether the material is effectively 
textured. The Colour column indicates whether the pixel map rendered to is indexed or ‘true’ colour 
(it is assumed that any texture shares this property). The ‘Pixels Set To’ column describes how each 
pixel of a face using the material is set. Note that ‘texel’ is the term used to refer to the element of 
the texture map corresponding to a particular screen pixel. 


No 
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Pixels Set To 


colour 
colour, uniformly illuminated by average face lighting 


colour, illuminated by linearly interpolated lighting 
between vertices 


Average prelit vertex colour 
Linearly interpolated between vertex prelit colours 
index_base 


index_base + index_range x (average face 
lighting) 

index_base + index_range x (linearly interpolated 
lighting between vertices) 

index_base + index_range xX (average vertex prelit 
index + 256) 

index_base + index_range  < (linear interpolation 
between vertex prelit indices + 256) 

Texel 


Texel uniformly illuminated by average face lighting 


Texel illuminated by linearly interpolated lighting 
between vertices 


Texel illuminated by average prelit vertex colour 


Texel illuminated by colour linearly interpolated 
between vertex prelit colours 


Texel 


Shade table: column [texel], row[index_base + 


index_range X (average face lighting)] 


Shade table: column [texel], row[index_base + 
index_range x (linearly interpolated lighting between 
vertices)] 


Shade table: column [texel], row[index_base + 


index_range x (average vertex prelit index)] 








Shade table: column 





texel], row[index_base + 
index_range x (linear interpolation between vertex 
prelit indices)] 


Table showing effects of different combinations of material lighting flags 


156 
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Lighting 
When a material is lit (BR_MATF_LIGHT is set, but not BR_MATF_PRELIT) a lighting calculation is 


performed to calculate the light reaching the viewer. This will depend upon the face’s orientation 
with respect to the viewer and the light sources. 


The following formula’ shows how the lighting A of a face depends upon 9, the angle at the face 
between the light source and the face normal, and 6, the angle at the face between the viewer and 
the reflected light ray. Note that with high k values it is apparently possible for A to be as large as 3, 
however A is clamped to the range [0,1). 


= P 
r _ Kantian + K diffuse COS 9 + K specularCOS 0) 


The other four variables in the equation are listed respectively, below. 


br_ufraction ka 


The ambient lighting contribution for lit materials. This is the amount of light assumed to be 
reflected from other objects and lighting in general, 1.e. not from light actors. This means that even 
ina scene with all lights disabled, a lit material will still be visible if it has a non-zero ambient lighting 
contribution. 


Zero can produce a material whose illumination is highly dependent upon light sources, whereas 
higher values can give ever fluorescent or luminous effects. 


A typical sunny scene might have most materials with a significant ambient contribution, whereas a 
dusk scene might have a much lower one, and a moonlit one, probably zero. 


br_ufraction kd 


The diffuse lighting contribution for lit materials. This determines how much of the reflected light 
is made up of the component dependent upon the angle of the face to the direction of the light 
illuminating it. The closer the face comes to being perpendicular to the light source, the more light 
the face receives, and thus the more diffuse light that can be reflected. 


Zero can give a shiny surface, whereas higher values can give surfaces a more matt appearance. 


br_ufraction ks 


The specular lighting contribution for this lit materials. This determines how much reflected light is 
made up of the component dependent upon the angle between the reflected light source and the 
direction of viewer (naturally, if the angle is zero, the component will be at its maximum). 


The greater the value, the more visible highlights will be. 


br_scalar power 


This member applies a power to the specular lighting contribution. 





* An approximation to the formula may be used on some platforms, particularly with respect to the specular term. 
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The greater the value, the sharper any highlights will be. A typical value is 20. 
Colour 


br colour colour 


When rendering in ‘true’ colour, the value of this member is taken as the basic colour of the face, 
which may of course be affected by lighting (if BR_MATF_LIGHT is set, but not BR_MATF_PRELIT). 


br_uint_8 index_base 


When rendering in indexed colour, this member determines the lower value of the index range used 
to colour a face. When lit, the light level is factored with index_range to obtain an index between 
index_base and index_base+index_range-1. Without lighting, index_base is used to set 
every pixel of the face. 


This member only applies to materials without textures - with textures, this member is ignored. 


br_uint_8 index_range 


When rendering in indexed colour, this member determines the number of index values that can be 
selected with a given lighting level, starting at index_base. 


‘This member only applies to materials without textures - with textures, this member is ignored. 


br_pixelmap * index_shade 


Materials with indexed colour texture maps can only be lit if they are accompanied by an appropriate 
shade table. The shade table is simply a way of tabulating the output pixel given a particular texel 
and a particular lighting level. The texel generally indexes the column and the lighting level, the row. 
The shade table must therefore have the full complement of columns necessary for the pixel size of 
the texture map. The shade table may have any number of rows, as the lighting level directly selects 
the row. 
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Thus an 8 bit indexed colour texture map requires a shade table with 256 columns and two or more 
rows (one being redundant). A selection of shade table types for use with 8 bit textures are described 
below. 


BR_PMT_INDEX_8 shade table to BR_PMT_INDEX_8 output 


The shade table converts 8 bit texels into 8 bit lit pixel values, by using the pixel 
in the shade table at the column given by the texel and the row given by the 
monochrome lighting level. 


BR_PMT_RGB_555 shade table to BR_PMT_RGB_555 output 


The shade table converts 8 bit texels into 15 bit lit pixel values, by using the pixel 
in the shade table at the column given by the texel and the row given by the 
monochrome lighting level. 


BR_PMT_RGBX_888 shade table to BR_PMT_INDEX_8 output 


The shade table converts 8 bit texels into 8 bit lit pixel values, by using a single 256 
column wide table, but with 24 bit colour values in order that true colour lighting 
can be applied. The red and green components of each value are actually column 
indices used to obtain a blue component which is produced as the output pixel. 
The table is thus read three times. 
1. X1=Red component of pixel in shade table at column(Texel), row(Red 

light level) 
2. X2=Green component of pixel in shade table at column(X1), row(Green 

light level) 
3. X3=Blue component of pixel in shade table at column(X2), row(Blue 

light level) 
4. Ouput pixel is X3 


br_pixelmap * index_blend 


Blending is a way of making the destination pixel depend upon the existing contents of the output 
buffer. The blend table like the shade table tabulates the output pixel given a particular texel and 
the pixel already in the output buffer. The texel indexes the column and the existing output pixel 
the row. The shade table must therefore have the full complement of rows as well as columns 
necessary for the pixel size of the texture map. 


Thus an 8 bit indexed colour texture map blend table needs 256 columns and 256 rows. The blend 
table is only used if BR_MATF_BLEND is set, and if set this member should not be NULL. 


Given that the blend table tabulates an output for every possible pair of input pixels, any function 
can be represented, e.g. exclusive-or, inverse, inclusive-or, mask, average, etc. 


The blend table is typically used for translucence effects, e.g. ghosts, flames, frosted glass, etc. 


Note that in the case of the depth buffer renderer, while the output pixel will only be written if it is 
nearer than the existing pixel, it will never modify the depth buffer value. This is because it is 
assumed to be an intangible surface. Therefore, it may be necessary to render such materials in a 
separate stage. 
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Note that if both a blend table and shade table is used (the material has an indexed texture which is 
lit and blended), the shade table is applied first, followed by the blend table. 


Blend tables, as with shade tables, also need to be added to the registry before use. 


Texture 


br_pixelmap * colour_map 


A pointer to a pixel map containing a pattern with which to cover faces using this material. 


Pixels that are zero in the pixel map are not further processed for colour information, and are 
effectively transparent. A face is not rendered where such pixels appear on its surface, nor are any 
corresponding values written to any depth buffer. Note though, that a 2D pick function will still pick 
a transparent face. For more sophisticated transparency effects see the description of index_blend 
above. 


Note that indexed colour textures must also have a corresponding shade table. 


br_matrix23 map_transform 


The transform to apply to texture co-ordinates. This enables textures to be rotated, scaled, sheared, 
and translated. Moreover, this transform can be continuously modified, thus providing animated 
texture effects. 


See BrModelApplyMap (),,; for details of how texture maps can be applied to a model’s faces. 


Supplementary 


char * identifier 


Pointer to unique, zero terminated, character string (or NULL if not required). Can be used as a handle 
to retrieve a pointer to the material. Not intended for intensive use. Typically used to collect pointers 
to materials loaded using BrMaterialLoad () ,,, and added to the registry using 

BrMaterialAdd () ,,. Also ideal for diagnostic purposes. 


A non-unique string can be supplied, but which of a set of materials having the same string will be 
matched by search functions (See BrMaterialFind () ,;), is undefined. Also in consideration of 
searching, it is not recommended that non-alphabetic characters are used, especially Slash (‘/’), 
Asterisk (‘*’), and Query (‘?’), which are used for pattern matching. 


This member can be modified by the programmer at any time. 


If identifier is set by BrMaterialLoad () ,,, ofr BeMaterialLoadMany () , it will have been 
constructed using BrResStrDup () 5. 
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void* user 


This member may be used by the application for its own purposes. It is initialised to NULL upon 
allocation, and not accessed by BRender thereafter. 


Copy/Assign 


The br_material,,, structure should not be copied directly, e.g. by structure assignment. Ifa 
similar material is required, a new one should be allocated and pertinent members copied 
individually. Care may be needed in copying identifier. 


Access & Maintenance 


Materials must be added to the registry if they are involved in rendering a scene. They should not be 
modified during rendering. 


Materials that have been added to the registry may be accessed by BRender during rendering. 


If any changes are made to materials involved in rendering, they must be updated before the next 
rendering in which they are involved. 


BrMaterialAdd () 


Description: | Adda material to the registry, updating it as necessary. All materials must be added 
to the registry before they are subsequently involved in rendering. 


Declaration: br_material* BrMaterialAdd(br_material* material) 
Arguments: br_material * material 
A pointer to a material. 
Result! br material * 
Returns a pointer to the added item, else NULL if unsuccessful. 


See Also: BrMaterialUpdate () ,., BeMaterialAddMany () |, BcMaterialLoad () is, 
BrMaterialFind () ,,;, BeMaterialRemove () 4. 


BrMaterialAddMany () 


Description: | Adda number of materials to the registry, updating them as necessary. 


Declaration: br_uint_32 BrMaterialAddMany (br_material* const* materials, 
int n) 


Arguments: br_material * const * materials 
A pointer to an array of pointers to materials. 
int n 


Number of materials to add to the registry. 
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Result: 


See Also: 


br_uint_32 
Returns the number of materials added successfully. 


BrMaterialUpdate () |, BrMaterialAdd () ,,,, BrMaterialRemove () |), 
BrMaterialRemoveMany () |; 


BrMaterialUpdate () 


Description: 


Declaration: 


Arguments: 


See Also: 


Update a material that has changed in some respect since the previous update of 
this material (or BeMaterialAdd () ,,,). 


void BrMaterialUpdate (br_material* material, 
br_uint_16 flags) 


br_material * material 


A pointer to a material. 
br_uint_16 flags 


Item update flags. In general, BR_MATU_ALL should be used. However, the 
following table describes when to use more specific update flags. Note that flags 
can be combined using the ‘Or’ operation (BR_MATU_ALL is such a combination 
of the other flags, for your convenience). 


Flag To Be Used When 

BR_MATU_MAP_TRANSFORM] The map_transform has been changed 
BR_MATU_RENDERING The flags member has been changed. 

BR_MATU_LIGHTING Lighting or Colour parameters have been changed. 
BR_MATU_COLOURMAP Elements of the texture at colour_map have been changed 
BR_MATU_ALL The change is unknown or wholesale. This includes the case when 


an entirely different texture map is being used, i.e. colour_map is 
set to a different pointer 


BrMaterialAdd () j¢). 


BrMaterialRemove () 


Description: 
Declaration: 
Arguments: 


Result: 


See Also: 


162 


Remove a material from the registry. 

br_material* BrMaterialRemove (br_material* material) 
br_material * material 

A pointer to a material. 

br_material * 

Returns a pointer to the item removed. 

BrMaterialAdd () ,,; 


Copyright © 1996 Argonaut Technologies Limited 


br_material 


BrMaterialRemoveMany () 


Description: | Remove a number of materials from the registry. 


Declaration: br_uint_32 
BrMaterialRemoveMany (br_material* const* materials, int n) 


Arguments: br_material * materials 
A pointer to an array of pointers materials. 
int n 
Number of materials to remove from the registry. 
Result! br_uint_32 
Returns the number of items removed successfully. 


See Also: BrMaterialAddMany () ,«; 


Referencing & Lifetime 


Materials may be multiply referenced. The texture map and any shade table may be referenced by 
more than one material as long as their lifetimes are longer than the materials that refer to them. 
Materials must have been added to the registry if they will be involved in rendering. The material 
must be maintained while it is in the registry or being referenced. 


Initialisation 


The material is automatically initialised to zero by BrMaterialAllocate() ,,,. Members should 
then be set appropriately. Re-initialisation is not recommended — destroy and reconstruct. 


Construction & Destruction 


Apart from import and platform specific functions, materials should only be constructed by the 
following BRender function. Destruction should naturally be performed by the corresponding ‘free’ 
function, usually BeMaterialFree () ,,,. Note that a material should be removed from the registry 
before being destroyed. 


BrMaterialAllocate () 


Description: — Allocate a new material. 
Declaration: br_material* BrMaterialAllocate (const char* name) 
Arguments: const char * name 


String to initialise the identifier member to. 
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Result: 


br_material * 


Returns a pointer to the new material, or NULL if unsuccessful. 


BrMaterialFree () 


Description: — Deallocate a material and any associated memory. 
Declaration: void BrMaterialFree(br_material* m) 
Arguments: br_material * m 
A pointer to a material. 
Supplementary 


BrMaterialCount () 


Description: 


Declaration: 


Arguments: 


Result: 


See Also: 


Count the number of registered materials whose names match a given search 
pattern. The search pattern can include the standard wild cards ‘*’ and °?’. 


br_uint_32 BrMaterialCount (const char* pattern) 
const char * pattern 

Search pattern. 

br_uint_32 

Returns the number of items matching the search pattern. 


BrMaterialEnum () ,,, BeMaterialFind() ,,; 


BrMaterialEnum () 


Description: 


Declaration: 


164 


Calls a call-back function for every material in the registry matching a given search 
pattern. The call-back is passed a pointer to each matching material, and its second 
argument is an optional pointer supplied by the user. The search pattern can 
include the standard wild cards ‘*’ and ‘?’. The call-back itself returns a 
br_uint_32,,, value. The enumeration will halt at any stage if the return value is 
non-Zero. 


br_uint_32 BrMaterialEnum(const char* pattern, 
br_material_enum_cbfn* callback, void* arg) 
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Result: 


Example: 
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const char * pattern 

Search pattern. 

br_material_enum_cbfn * callback 

A pointer to a call-back function. 

void * arg 

An optional argument to pass to the call-back function. 
br_uint_32 


Returns the first non-zero call-back return value, or zero if all matching items are 
enumerated. 


br_uint_32 BR_CALLBACK test_callback (br_material* material, void* 


arg) 
br_uint_32 count; 


return(count); 


br_uint_32 enum; 


enum = BrMaterialEnum(“material”, &test_callback, NULL); 


BrMaterialFind () 


Description: 


Declaration: 


Arguments: 


Result: 


See Also: 


Find a material in the registry by name. A call-back function can be setup to be 
called if the search is unsuccessful. The search pattern can include the standard 
wild cards ‘*’ and ‘?’. 


br_material* BrMaterialFind(const char* pattern) 
const char * pattern 

Search pattern. 

br_material * 


Returns a pointer to the material if found, otherwise NULL. Ifa call-back exists and 
is called, the call-back’s return value is returned. 


BrMaterialFindHook () |, BeMaterialFindMany () \; 


BrMaterialFindMany () 


Description: 


Find a number of materials in the registry by name. The search pattern can include 
the standard wild cards ‘*’ and ‘?’. 
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Declaration: 


Arguments: 


Result: 


See Also: 


br_uint_32 BrMaterialFindMany (const char* pattern, 
br_material** materials, int max) 


const char * pattern 

Search pattern. 

br_material ** materials 

A pointer to an array of pointers to materials. 
int max 

Maximum number of materials to find. 
br_uint_32 


Returns the number of materials found. The pointer array is filled with pointers to 
the found materials. 


BrMaterialFind () ,,,, BceMaterialFindHook () 4 


BrMaterialFindHook () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


Example: 


Functions to set up a call-back. 


br_material_find_cbfn* 
BrMaterialFindHook (br_material_find_cbfn* hook) 


br_material_find_cbfn * hook 
A pointer to a call-back function. 


If BreMaterialFind () ,,; is unsuccessful and a call-back has been set up, the call- 
back is passed the search pattern as its only argument. The call-back should then 
return a pointer to a substitute or default item. 


For example, a call-back could be set up to return a default material if the desired 
material cannot be found in the registry. 


The function BrMaterialFindFailedLoad() is provided and will probably 
be sufficient in many cases. 


br_material_find_cbfn * 


Returns a pointer to the old call-back function. 


br_material BR_CALLBACK * test_callback(const char* pattern) 


{ 
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br_material* default_material; 


return (default_material); 


br_material* material; 


BrMaterialFindHook (&test_callback) ; 


material = BrMaterialFind(”“non_existent_material”); 
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BrMaterialFindFailedLoad() | 


BrMaterialFindFailedLoad () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


Example: 


This function is provided as a suitable function to supply to 
BrMaterialFindHook () 16. 


br_material* BrMaterialFindFailedLoad(const char* name) 
const char * name 
The name supplied to BrMaterialFind () 5. 


Attempts to load the material from the filing system using name as the filename. 
Searches current directory, if not found tries, in order, the directories listed in 
BRENDER_PATH (if defined). If successful, sets this name as the identifier of 
the loaded material and adds the material to the registry. 


br_material * 


Returns a pointer to the material, if found, else NULL. 


BrMaterialFindHook (BrMaterialFindFailedLoad) ; 


Import & Export 


BrMaterialFileCount () 


Description: 


Declaration: 


Arguments: 


Effects: 


Locate a given file and count the number of materials in it. 


br_uint_32 BrMaterialFileCount (const char* filename, 
br_uint_16* num) 


const char * filename 

Name of the file containing the materials to count. 

br_uint_16 * num 

Pointer to the variable in which to store the number of materials counted in the file. 


If NULL, the file will still be located and appropriate success returned, but no count 
will be made. 


Searches for filename, if no path specified with file looks in current directory, if 
not found tries, in order, the directories listed in BRENDER_PATH (if defined). 
Ifa file is found, will count the number of materials stored in it. 
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Result: 


br_uint_32 


Returns zero if the file was found (even if it is not a materials file), non-zero 
otherwise. 


BrMaterialLoad () 


Description: 
Declaration: 


Arguments: 


Effects: 


Result: 


See Also: 


Load a material. Note that it is not added to the registry. 
br_material* BrMaterialLoad(const char* filename) 
const char * filename 

Name of the file containing the material to load. 


Searches for filename, if no path specified with file looks in current directory, if 
not found tries, in order, the directories listed in BRENDER_PATH (if defined). 


br_material * 
Returns a pointer to the loaded material, or NULL if unsuccessful. 


BrMaterialLoadMany () ,., BeMaterialSave () |, BeMaterialAdd () ,¢). 


BrMaterialLoadMany () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


See Also: 
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Load a number of materials. Note that they are not added to the registry. 


br_uint_32 BrMaterialLoadMany (const char* filename, 
br_material** materials, br_uint_16 num) 


const char * filename 

Name of the file containing the materials to load. 
br_material ** materials 

A non-NULL pointer to an array of pointers to materials. 
br_uint_16 num 

Maximum number of materials to load. 


Searches for filename, if no path specified with file looks in current directory, if 
not found tries, in order, the directories listed in BRENDER_PATH (if defined). 


br_uint_32 


Returns the number of materials loaded successfully. The pointer array supplied, 
is filled with pointers to the loaded materials. 


‘To determine how many materials are stored in a file see 
BrMaterialFileCount () \,. 
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BrFmtScriptMaterialLoad () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


Example: 








Load a material from a material script. Note that all maps and tables in a script 
should be already loaded and registered. If not, this function can be combined with 
BrMapFindHook (),,; and BrTableFindHook (),,, to facilitate rapid setup of 
materials with textures. 


br_material* BrFmtScriptMaterialLoad(const char* filename) 
const char * filename 
Name of the file containing the material script. 


Searches for filename, if no path specified with file looks in current directory, if 
not found tries, in order, the directories listed in BRENDER_PATH (if defined). 


br_material * 
Returns a pointer to the loaded material, or NULL if unsuccessful. 


Material scripts are formatted as follows: 
Comment 
Fields may be given in any order or omitted 


(a sensible default will be supplied) 


Extra white spaces are ignored 


material= 


name = "foo"; 
flags= 
[ 


light,prelit, smooth, environment, environment_local, perspective, 
decal, always_visible, two_sided, force_z_0 

li 

colour = [10,10,20]; 

ambient = 0.10; 

diffuse = 0.70; 


specular = 0.40; 


power = 30; 

map_transform = [[1,0], [0,1], [0,0]]; 
index_base = 0; 

index_range = 0; 

colour_map = "brick"; 

index_shade = "shade.tab"; 
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BrFmtScriptMaterialLoadMany () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


Load a number of materials from a material script. 


br_uint_32 
BrFmtScriptMaterialLoadMany (const char* filename, 
br_material** materials, br_uint_16 num) 


const char * filename 

Name of the file containing a number of concatenated material script entries. 
br_material ** materials 

A non-NULL pointer to an array of pointers to materials. 

br_uint_16 num 

Maximum number of materials to load. 


Searches for filename, if no path specified with file looks in current directory, if 
not found tries, in order, the directories listed in BRENDER_PATH (if defined). 


br_uint_32 


Return the number of materials loaded successfully. The pointer array if supplied, 
is filled with pointers to the loaded materials. 


BrMaterialSave () 


Description: 


Declaration: 


Arguments: 


Effects: 
Result: 


See Also: 


Save a material to a file. 


br_uint_32 BrMaterialSave(const char* filename, 
const br_material* material) 


const char * filename 

Name of the file to save the material to. 

const br_material * material 

A pointer to a material. 

Writes the material to a file’. 

br_uint_32 

Returns NULL if the material could not be saved. 


BrWriteModeSet () ,, 


BrMaterialSaveMany () 


Description: 


Save a number of materials to a file. 





* 
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Any existing file of the same name is overwritten. 
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Declaration: 


Arguments: 


Effects: 


Result: 


See Also: 


br_material 


br_uint_32 BrMaterialSaveMany (const char* filename, 
const br_material* const* materials, br_uint_16 num) 


const char * filename 
Name of the file to save the materials to. 
const br_material * const * materials 


A pointer to an array of pointers to materials. If NULL, all registered materials are 
saved (irrespective of num). 


br_uint_16 num 

Number of materials to save. 

Writes the materials to a file’. 

br_uint_32 

Returns the number of materials saved successfully. 


BrWriteModeSet () ,, 


Platform Specific 


The supported combinations of material flags vary from platform to platform. The supported 
dimensions of texture maps are also platform dependent. 





* 


Any existing file of the same name is overwritten. 
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br_material_enum_cbfn 


br material enum _cbfn 


The Call-Back Function 


This type defines a function, supplied to BeMaterialEnum () ,,,, and to be called by it for a selection 


of materials. 


The typedef 


(See fwproto.h fora precise declaration) 


br_uint_32 


br_material_enum_cbfn(br_material*, void *) Enumerator 


Specification 


CBFnMaterialEnum () 


Description: 
Declaration: 


Arguments: 


Preconditions: 
Effects: 
Result: 


See Also: 
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An application defined call-back function accepting a material and an application 
supplied argument (as supplied to BeMaterialEnum () ,,,). 


br_uint_32 BR_CALLBACK CBFnMaterialEnum(br_material* mat, 
void* arg) 

br_material * mat 

One of the resource classes selected by BrMaterialEnum () ,q. 

void * arg 

The argument supplied to BrMaterialEnum () j,.. 

BRender has completed initialisation. 

Application defined. Avoid adding or removing materials within this function. 
br_uint_32 

Any non-zero value will terminate the enumeration and be returned by 
BrMaterialEnum () ,,. Return zero to continue the enumeration. 


BrMaterialEnum () ,,, BeMaterialFind () ,,;. 
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br_material_find_cbfn 


br material find cbfn 


‘The Call-Back Function 


This type defines a function, registered with BrMaterialFindHook () ,, to be called when 
BrMaterialFind() ,; or BrMaterialFindMany () ,,; fail to find any material. 


The typedef 

(See fwproto.h fora precise declaration) 

br_material* br_material_find_cbfn(const char*) Find (when BrMaterialFind() 
fails) 

Specification 


CBFnMaterialFind () 


Description: | An application defined call-back function used when BrMaterialFind () ,; or 
BrMaterialFindMany () \5 fail. 


Declaration: br_material* BR_CALLBACK CBFnMaterialFind(const char* name) 
Arguments: const char * name 
The search pattern supplied to BrMaterialFind () ,; or 
BrMaterialFindMany () ,; that did not match any material. 


Preconditions: | BRender has completed initialisation. No material has an identifier that 
successfully matches the search pattern. 


Effects: Application defined. 


Result: br_material * 


Either return an existing material that is deemed appropriate for the search pattern, 
or NULL if there isn’t one. This value will be returned by BrMaterialFind () (5 
or BrMaterialFindMany () ,;;. 


Remarks: — This could either be used to supply a default material or to create a material. If 
materials were created on demand, then this function could search another list of 
available materials (but not yet created) and see if the pattern matched any of them, 
if it did, one of them could be registered and returned. Note that there is no way to 
supply more than one material. 


See Also: BrMaterialFind() ,,,, BeMaterialFindMany () ,,;, 
BrMaterialFindHook () ,,,, BeMaterialFindFailedLoad () ,,,. 
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br matrix23 


The Structure 


A two column, three row, scalar array, used as a 2D affine matrix, typically for texture map 
transformations (translation, scaling, shearing, rotation). Functions are provided to allow it be used as 
though it were an integral type. It has the following form: 


Moy Mo, 
Mig My, 
Mog Mp 


Note that this is effectively used as a 3x3 matrix, but omitting the redundant, third column for storage 
purposes. Thus: 


Moy Mo, O 

Mig my, O 

My My, 1 
It is applied to homogenous 2D co-ordinates, which similarly omit the third element for sake of 
economy. 


It can be noted that the bottom row has a translational effect. Also note, that the matrix determinant 
represents the area change effected. 


The typedef 


(See matrix.h for precise declaration and ordering) 
br_scalar m[3] [2] Three rows of two columns 


Related Structures 


See br_material,,,. 


Members 


br_scalar m[3] [2] 


Each element of the matrix can be freely and individually accessed. 


This matrix can also be thought of as an array of three br_vector2,,, structures, e.g. br_vector2 
m[3]. Thus m[row] can be cast as (br_vector2*). 
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Arithmetic 


BrMatrix23Mul () 


Description: 


Declaration: 


Arguments: 


Remarks: 


See Also: 


bo bo, 9 Cop Co 9 
Diy Dy OF] Cy Cy OF 


boy by, 1 Co Cy, 1 


Multiply two matrices together and place the result in a third matrix. Equivalent to 
the expression: 


A<—BC 


void BrMatrix23Mul (br_matrix34* A, const br_matrix34* B, 
const br_matrix34* C) 


br_matrix23 * A 

A pointer to the destination matrix (must be different from both sources). 
const br matrix23 * B 

Pointer to the left hand source matrix. 

const br matrix23 * C 

Pointer to the right hand source matrix. 


The result in A is equivalent to the following: 


boo€o0 + B01¢10 boofo1 + P0111 


bi€o0 + P1110 bilo + Oey 


boo€o9 + O21 C10 + 29 Ba0€o1 + P2111 + ©r1 


BrMatrix23Pre() ,,, BrMatrix23Post () |.) 


BrMatrix23Inverse () 


Description: 


Declaration: 


Arguments: 


Result: 
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Compute the inverse of the supplied matrix. Equivalent to the expression: 


AcB'! 


br_scalar BrMatrix23Inverse (br_matrix23* A, 
const br_matrix23* B) 


br_matrix23 * A 


A pointer to the destination matrix (must be different from source). 


const br_matrix23 * B 


A pointer to the source matrix. 


br_scalar 


If the inverse exists, the determinant of the source matrix is returned. If there is no 
inverse, scalar zero is returned. 
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br_matrix23 


Remarks: The result in A is equivalent to the following: 


Dy —bo, 0 
boo by, 0) [BI Br 
00 “O01 =F , 
by Bie 0: |= Br BI 0 
by b>, 1 
aoe se (Diob2, = Dy, by9) (bo P29 as bogbr1) 





BE BE 


See Also: BrMatrix23LPInverse () ,,. 


BrMatrix23LPInverse () 


Description: | Compute the inverse of the supplied length preserving’ transformation matrix. The 
resulting matrix is undefined for non-length preserving matrices. 


Equivalent to the expression: 
Arp = Bip 
Declaration: void BrMatrix23LPInverse (br_matrix23* A, 
const br_matrix23* B) 
Arguments: br_matrix23 * A 
A pointer to the destination matrix (must be different from source). 
const br_matrix23 * B 
A pointer to the source matrix. 


Remarks: ‘The result in A is equivalent to the following: 
-l 


boy Do O by —boy 0 
by by O = dig boo 0 
by by, 1 ~ Digby, — Bybo9 By B29 — Bopha, I o 


See Also: BrMatrix23Inverse () ,;. 


BrMatrix23ApplyP () 
Description: | Applies a transform to a 2D point. Equivalent to the expression: 


RH PBC 





* Note that length preserving also applies to the sign of lengths, not just their magnitude, i.e. a reflection is not 
length preserving in this case. 
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Declaration: void BrMatrix23ApplyP (br_vector2* A, const br_vector2* B, 
const br_matrix23* C) 


Arguments: br_vector2 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed point. 


const br_vector2 * B 


A pointer to the source vector, holding the point to be transformed. 


const br_matrix23 * C 


A pointer to the transform matrix to be applied. 


Remarks: The result in A is equivalent to the following: 


Coo Cor O 
(xe ye 1) Cy C11 O | = (xgcoot+yecio t+ C2 XeCor t+ Yeu ten 1) 


Co Cy 1 


BrMatrix23ApplyvV () 


Description: Applies a transform to a 2D vector, i.e. as for a point but without translation 
components (a vector has no location). Equivalent to the expression: 


VA co VpC 
Declaration: void BrMatrix23ApplyV(br_vector2* A, const br_vector2* B, 
const br_matrix23* C) 


Arguments: br_vector2 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed vector. 


const br_vector2 * B 

A pointer to the source vector, holding the vector to be transformed. 
const br_matrix23 * C 

A pointer to the transform matrix to be applied. 


Remarks: ‘The result in A is equivalent to the following: 


Coo Cor O 
(xg ye OD Cy Cy O | =Cegcoo+yeeio XBCor + Yee, 0) 
Co Cy | 
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BrMatrix23TApplyP () 


Description: Applies a transposed transform to a 2D point. Equivalent to the expression: 
t 
P= PC 
Declaration: void BrMatrix23TApplyP (br_vector2* A, const br_vector2* B, 


const br_matrix23* C) 


Arguments: br_vector2 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed point. 


const br_vector2 * B 


A pointer to the source vector, holding the point to be transformed. 


const br_matrix23 * C 


A pointer to the transform matrix to be applied transposed — the translation 
elements are presumed zero or irrelevant. 


Remarks: ‘The result in A is equivalent to the following: 
Coo Cor O |] Xp Coore + Cory 


Cio Cy O Ye |=] CioXpt+Ciuye 
| 1 1 


BrMatrix23TApplyV () 


Description: | Applies a transposed transform to a 2D vector, i.e. as for a point but without 
translation components (a vector has no location). Equivalent to the expression: 
t 
VA = VB C 
Declaration: void BrMatrix23TApplyV(br_vector2* A, const br_vector2* B, 
const br_matrix23* C) 
Arguments: br_vector2 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed vector. 


const br_vector2 * B 


A pointer to the source vector, holding the vector to be transformed. 


const br_matrix23 * C 


A pointer to the transform matrix to be applied transposed — the translation 
elements are presumed zero or irrelevant. 
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Remarks: The result in A is equivalent to the following: 
Co Cor 9 || Xe CoorB + CoB 


Cio Cy O Ye |=| CixXpt+ Cue 
a a | 0 0 


BrMatrix23Pre () 


Description: | Pre-multiply one matrix by another. Equivalent to the expression: 
A<=BA 
Declaration: void BrMatrix23Pre(br_matrix23* A, const br_matrix23* B) 
Arguments: br_matrix23 * A 
A pointer to the subject matrix (may be same as B). 
const br_matrix23 * B 
A pointer to the pre-multiplying matrix. 


Remarks: The result in A is equivalent to the following: 


boo Po 9 \f a0 41 9 99400 + 401410 boo4o1 + P0141 
Dig Dy OF ayy 41, 9 JF} Bi9400 + 11410 bid + Oy 
boy by, 1 Ary Ay, | by + 21419 + 429 P9401 + P2141, +41 I 


See Also: BrMatrix23Post () |, BreMatrix23Mul () ,,, 


BrMatrix23PreTranslate () 


Description: | Pre-multiply a matrix by a translation transform matrix. Equivalent to the 
expression: 


M<=T,,M 
Declaration: void BrMatrix23PreTranslate(br_matrix23* mat, br_scalar dx, 
br_scalar dy) 
Arguments: br_matrix23 * mat 


A pointer to the subject matrix. 


br_scalar dx 


‘The x axis component used to form the translation matrix. 


br_scalar dy 


The y axis component used to form the translation matrix. 
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Remarks: The result in mat is equivalent to the following: 


1 0.0 |f m0 mM; 9 Moo Mo 0 
010 My M1, 0 |=} Moo Mo 0 
6, 5, 1 My My, 1 5,Mq9 + SyMg + My 8,Mp, +H, + Mg, I 
See Also: 


BrMatrix23PostTranslate() ,.;,, BeMatrix23Translate () j., 


BrMatrix23PreScale () 


Description: | Pre-multiply a matrix by a scaling transform matrix. Equivalent to the expression: 


M <=S,,M 
Declaration: void BrMatrix23PreScale(br_matrix23* mat, br_scalar sx, 
br_scalar sy) 
Arguments: br_matrix23 * mat 
A pointer to the subject matrix. 
br_scalar sx 
Scaling component along the x axis. 
br_scalar sy 
Scaling component along the y axis. 


Remarks: The result in mat is equivalent to the following: 


Ss, 0 0 |{ mq mo, O S,Moy S,Mo, O 
0 s, 0 |} mio my O SyMyy Sym, O 
0: 081 My My, 1 My My, 1 


See Also: BrMatrix23PostScale() ,,,, BreMatrix23Scale () .. 


BrMatrix23PreShearxX () 


Description: | Pre-multiply a matrix by an x invariant shearing transform matrix. Equivalent to the 


expression: 


M<=Z,M 


Declaration: void BrMatrix23PreShearxX (br_matrix23* mat, br_scalar sy) 
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Arguments: br_matrix23 * mat 
A pointer to the subject matrix. 
br_scalar sy 


Shear factor by which the x co-ordinate is included in the transformed y co- 
ordinate. 


Remarks: The result in mat is equivalent to the following: 


1 6, 0 |/ oo ™o1 0 Moy + OyM1y My, +Oym,, O 
0 1 0 4f] Mo my, 9 |= M1 my, 
0 0 L)\m 9 ms, 1 My My 


See Also: BrMatrix23PostShearxX () ,,,, BeMatrix23ShearxX () |, 


BrMatrix23PreShearY () 


Description: — Pre-multiply a matrix bya y invariant shearing transform matrix. Equivalent to the 
expression: 


M<=Z,M 


Declaration: void BrMatrix23PreShearY (br_matrix23* mat, br_scalar sx) 
Arguments: br_matrix23 * mat 
A pointer to the subject matrix. 


br_scalar sx 


Shear factor by which the y co-ordinate is included in the transformed x co- 
ordinate. 


Remarks: The result in mat is equivalent to the following: 


1.00 |{ M0 mM, 9 Mo Mo, 0 
6,10 |fmy my 0) =| oymy tim OM, +m, 0 
0 O1 JY my 1 My My, 1 


See Also: BrMatrix23PostShearY () ,.,, BeMatrix23ShearY () 5 
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BrMatrix23PreRotate () 


Description: | Pre-multiply a matrix by a rotational transform matrix. Equivalent to the 
expression: 


M=R,M 


Declaration: void BrMatrix23PreRotate (br_matrix23* mat, br_angle rz) 
Arguments: br_matrix23 * mat 

A pointer to the subject matrix. 

br_angle rz 

The clockwise angle about the z axis used to form the rotation matrix. 


Remarks: The result inmat is equivalent to the following: 


cos8, sin®, 0 Moy Mo, O Mj C089, + M49sinB, mg, cos8,+m,,sin8, 0 
—sin®, cos6. 0 My my, 0 |= —MysinO, + m,ycosO, —mp,sin8, + m,,cos8, 0 
0 0 1 Moy Mo, 1 My M, 1 


See Also: BrMatrix23PostRotate () ,;, BrMatrix23Rotate () j99 


BrMatrix23Post () 


Description: | Post-multiply one matrix by another. Equivalent to the expression: 
A = AB 


Declaration: void BrMatrix23Post (br_matrix23* A, const br_matrix23* B) 
Arguments: br_matrix23 * A 

A pointer to the subject matrix (may be same as B). 

const br_matrix23 * B 

A pointer to the post-multiplying matrix. 


Remarks: The result in A is equivalent to the following: 


Ay 4, O bo bo, 9 AP o0 + 401 10 AggPo + 401911 0 
ai 4, O Diy yy 9 JF] ay9bo9 + 411 P10 Ayybo + 44,91) 0 
Any ay, | boy by, 1 Argo + 42119 + O99 4y9F01 + 42191, +42, 1 


See Also: BrMatrix23Pre() ,., BeMatrix23Mul () ,,;. 
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BrMatrix23PostTranslate () 


Description: — Post-multiply a matrix by a translation transform matrix. Equivalent to the 
expression: 


M = MI,, 
Declaration: void BrMatrix23PostTranslate (br_matrix23* mat, br_scalar dx, 
br_scalar dy) 
Arguments: br_matrix23 * mat 
A pointer to the subject matrix. 
br_scalar dx 
‘The x axis component used to form the translation matrix. 
br_scalar dy 


The y axis component used to form the translation matrix. 


Remarks: ‘The result inmat_ is equivalent to the following: 


Moy Moy 0 1 0O 0 Moo Mo, 0 
Mig Mm, O 0 1 O}F Mi my, 0 
Moy My, 1 5, 5, 1 M+, mM, + 5, 1 


See Also: BrMatrix23PreTranslate() ,,, BreMatrix23Translate () \... 


BrMatrix23PostScale () 


Description: — Post-multiply a matrix by a scaling transform matrix. Equivalent to the expression: 


M = MS,, 
Declaration: void BrMatrix23PostScale(br_matrix23* mat, br scalar sx, 
br_scalar sy) 
Arguments: br_matrix23 * mat 


A pointer to the subject matrix. 


br_scalar sx 


Scaling component along the x axis. 


br_scalar sy 


Scaling component along the y axis. 
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Remarks: The result in mat is equivalent to the following: 


0 0 MoS M15, O 
8, O | =] mys, m1,8, 0 
1 


0 
Mr Mz, 1 0 0 M708 x MS 1 


See Also: BrMatrix23PreScale () |, BrMatrix23Scale () 4. 


BrMatrix23PostShearx () 


Description: | Post-multiply a matrix by an x invariant shearing transform matrix. Equivalent to 
the expression: 


M<MZ, 


Declaration: void BrMatrix23PostShearxX (br_matrix23* mat, br_scalar sy) 
Arguments: br_matrix23 * mat 
A pointer to the subject matrix. 


br_scalar sy 


Shear factor by which the x co-ordinate is included in the transformed y 
co-ordinate. 


Remarks: ‘The result inmat is equivalent to the following: 


Moy Mo, O |f 1 0, 0 Moy MoyOy+ Mo, O 
Mo M, O}0 1 O |=] Mo MyO,+m, O 
My M, 1/\0 O 1 Mr Mz90,+M, 1 


See Also: BrMatrix23PreShearX () ,, BrMatrix23Shearx () js. 


BrMatrix23PostShearY () 


Description: | Post-multiply a matrix bya y invariant shearing transform matrix. Equivalent to the 
expression: 


M<MZ, 


Declaration: void BrMatrix23PostShearY (br_matrix23* mat, br scalar sx) 


Arguments: br_matrix23 * mat 


A pointer to the subject matrix. 


br_scalar sx 


Shear factor by which the y co-ordinate is included in the transformed x 
co-ordinate. 
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Remarks: The result in mat is equivalent to the following: 


Moy Mo, 0 1 00 Moy + M919, Mo, 0 
My my, O |}o, 1 0 | =|miy+m,,0, m, O 
My Mz, 1/)\O0 0 1 My) +710, My, | 


See Also: BrMatrix23PreShearY () ,,,, BeMatrix23ShearyY () j,0. 


BrMatrix23PostRotate () 


Description: | Post-multiply a matrix by a rotational transform matrix. Equivalent to the 
expression: 


M<=MR,, 


Declaration: void BrMatrix23PostRotate (br_matrix23* mat, br_angle rz) 
Arguments: br_matrix23 * mat 

A pointer to the subject matrix. 

br_angle rz 

The clockwise angle about the z axis used to form the rotation matrix. 


Remarks: The result in mat is equivalent to the following: 


Moy Mo, O cos@, sin®, 0 MgyCOSO,—Mp)sinB, moqsin®, + mg, cos, 
My m,, O —sin0, cos8, 0 |= m,jcos®,—m,,sin8, m, sin®, + m,,cos0, 
My, My, 1 0 Oo 1 M)COSO,—my,sinB, my )sinO,+m,cos8, | 


See Also: BrMatrix23PreRotate() ,», BrMatrix23Rotate () jy. 


Copy/Assign 


Although copy by structure assignment currently works, use BrMat rix23Copy () ,,; to ensure 
compatibility. 


BrMatrix23Copy () 
Description: | Copy a matrix. Equivalent to the expression: 
A<=B 


Declaration: void BrMatrix23Copy (br_matrix23* A, const br_matrix23* B) 
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Arguments: 


br_matrix23 * A 


A pointer to the destination matrix (may be the same as source — though 
redundant). 


const br _ matrix23 * B 


A pointer to the source matrix. 


Access & Maintenance 


Members may be freely accessed. Maintenance is only required for length preserving matrices that 


have been modified. 


BrMatrix23LPNormalise () 


Description: 


Declaration: 


Arguments: 


Effects: 


Remarks: 


Normalise a length preserving” matrix. Equivalent to the expression: 


A,p = Norm(B_,;p) 


void BrMatrix23LPNormalise(br_matrix23* A, 
const br_matrix23* B) 


br_matrix23 * A 

A pointer to the destination matrix, which must not point to the source matrix. 
const br_matrix23 * B 

A pointer to the source matrix. 


The destination matrix is the source matrix adjusted so that it represents a length 
preserving transformation. 


This function is typically applied to a length preserving matrix which has 
undergone a long sequence of operations, to ensure that the final matrix is still truly 
length-preserving. 


Referencing & Lifetime 


This structure may be freely referenced, though take care if there is potential to supply the same 
matrix as more than one argument to the same function. 





* 


Note that length preserving also applies to the sign of lengths, not just their magnitude, i.e. a reflection is not 


length preserving in this case. 
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Initialisation 
No static initialisers are provided, however, three BR_VECTOR2() macros would serve as well. 


All other initialisation should use the functions BrMatrix23Identity () |.) 
BrMatrix23Translate() ,,,, BeMatrix23Scale() ,.., BreMatrix23Shear[XIY] () jgeiso» 
BrMatrix23Rotate () ,,,, or BeMatrix23Copy () ,,;. 


BrMatrix23Identity () 


Description: Set the specified matrix to the identity transformation matrix. Equivalent to: 


10 0 
M<I=/ 0 1 0 


0 0 1 


Declaration: void BrMatrix23Identity (br_matrix23* mat) 
Arguments: br_matrix23 * mat 
A pointer to the destination matrix. 


Effects: Stores the identity matrix at the destination. 


BrMatrix23Translate () 


Description: Set the specified matrix to a matrix representing a specific translation. 
Equivalent to: 


Declaration: void BrMatrix23Translate(br_matrix23* mat, br scalar dx, 
br_scalar dy) 


Arguments: br_matrix23 * mat 


A pointer to the destination matrix. 


br_scalar dx 


Translation component along the x axis. 


br_scalar dy 
‘Translation component along the y axis. 


See Also: BrMatrix23PreTranslate () ,,», BrMatrix23PostTranslate () 3. 
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BrMatrix23Scale () 


Description: Set the specified matrix to a matrix representing a specific scaling. Equivalent to: 


s, O O 
M<=S,,=| 0 s, 0 


0 0 1 


Declaration: void BrMatrix23Scale(br_matrix23* mat, br_scalar sx, 
br_scalar sy) 


Arguments: br_matrix23 * mat 


A pointer to the destination matrix. 


br_scalar sx 


Scaling component along the x axis. 


br_scalar sy 
Scaling component along the y axis. 


See Also: BrMatrix23PreScale () ,, BrMatrix23PostScale () ,;. 


BrMatrix23ShearxX () 


Description: Set the specified matrix to a matrix representing a shear, invariant along the x axis. 
Thus values of y co-ordinates will be scaled in proportion to the value of the x co- 
ordinate. Equivalent to: 


1 0, 0 
M<=Zy=| 0 1 O 
00 1 


Declaration: void BrMatrix23ShearxX (br_matrix23* mat, br_scalar sy) 
Arguments: br_matrix23 * mat 

A pointer to the destination matrix. 

br_scalar sy 


Shear factor by which the x co-ordinate is included in the transformed y co- 
ordinate. 


See Also: BrMatrix23PreShearxX () ,, BrMatrix23PostShearx () js. 
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BrMatrix23ShearY () 


Description: Set the specified matrix to a matrix representing a shear, invariant along the y axis. 
Thus values of x co-ordinates will be scaled in proportion to the value of the y co- 
ordinate. Equivalent to: 


1 O 0 
M<Z,= Oo, 1 O 


OO J 


Declaration: void BrMatrix23ShearxX (br_matrix23* mat, br_scalar sx) 
Arguments: br_matrix23 * mat 

A pointer to the destination matrix. 

br_scalar sx 


Shear factor by which the y co-ordinate is included in the transformed x co- 
ordinate. 


See Also: BrMatrix23PreShearY () ,,,, BeMatrix23PostShearY () ,,,. 


BrMatrix23Rotate () 


Description: Set the specified matrix to a matrix representing a rotation about the z axis though 
a specified angle. Equivalent to: 


cos8, sin@, 0 
M<=R,, =| -sin®, cos@, 0 
0 0 1 


Declaration: void BrMatrix23Rotate(br_matrix23* mat, br_angle rz) 
Arguments: br_matrix23 * mat 


A pointer to the destination matrix. 


br_angle rz 
Clockwise rotation about the z axis. 


See Also: BrMatrix23PreRotate () ,,, BeMatrix23PostRotate () 35. 
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The Structure 


A three column, four row, scalar array, used as a 3D affine matrix for general purpose 3D 
transformations (translation, scaling, shearing, rotation). Functions are provided to allow it be used as 
though it were an integral type. It has the following form: 


Moy Mo, Mo 
Mig My My 
My Mz, My) 
M3g 113, N39 


Note that this is effectively used as a 4x4 matrix, but omitting the redundant, fourth column for 
storage purposes. Thus: 


= 

S 

= 

3 

S 
a a a 


It is applied to homogenous 3D co-ordinates, which similarly omit the fourth element for sake of 
economy. 


It can be noted that the bottom row has a translational effect. Also note, that the matrix determinant 
represents the volume change effected. 


The typedef 


(See matrix.h for precise declaration and ordering) 
br_scalar m[4] [3] Four rows of three columns 


Related Functions 


Scene Modelling 


See BrActorToActorMatrix34 () ,). 


Maths 


See BrMatrix4Pre34 () .», BrMatrix4Copy34 () 16. 
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Miscellaneous 


See BrMatrix34RollingBal11 () q. 


Related Structures 


See br_matrix4,,,, br_material,,,, br_pick3d_cbfn,,,. 


Members 


br_ scalar m[4] [3] 


Each element of the matrix can be freely and individually accessed. 


This matrix can also be thought of as an array of four br_vector3,,, structures, e.g. br_vector3 
m[4]. Thus m[row] can be cast as (br_vector3*). 


Arithmetic 


BrMatrix34Mul () 


Description: | Multiply two matrices together and place the result in a third matrix. Equivalent to 
the expression: 


A<—BC 


Declaration: void BrMatrix34Mul (br_matrix34* A, const br_matrix34* B, 
const br_matrix34* C) 


Arguments: br_matrix34 * A 


A pointer to the destination matrix (must be different from both sources). 


const br_matrix34 * B 


Pointer to the left hand source matrix. 


const br_matrix34 * C 


Pointer to the right hand source matrix. 
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Remarks: The result in A is equivalent to the following: 

bo Fo 22 9 Cop Cor Con 9 

by by Py 9 Cio Cu C12 9 = 

by by, by 0 C9 Cn CaO 

bx b3, by 1 C39 C3, C39_—s IL 

boo€o0 + Bo1€10 + Bo2€20 boo€o1 + Bore 11 + Bo2€21 booo2 + B01 12 + Bo2€22 0 
DiCoo + B11€19 + B12€29 Dio. + By C41 + ByQCr} DyoCon + By C12 + ByCr 0 
boo €o9 + P2119 + 9229 boo€o1 + O21 C11 + 922€D4 boo €o2 + P2112 + B99€99 0 
b39€o9 + P3119 + 432€90 + C39 P3001 + 931611 + 932621 + ©3514 — 230C02 + 931€12 + 93222 + C32 I 


See Also: 


BrMatrix34Pre () ,.,, BrMatrix34Post () 5 


BrMatrix34Inverse () 


Description: 


Compute the inverse of the supplied 3D affine matrix. Equivalent to the 
expression: 


AcB'! 


Declaration: 


Arguments: 


Result: 


Remarks: 


See Also: 
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br_scalar BrMatrix34Inverse (br_matrix34* A, 
const br_matrix34* B) 


br_matrix34 * A 

A pointer to the destination matrix (must be different from source). 
const br_matrix34 * B 

A pointer to the source matrix. 

br_scalar 


If the inverse exists, the determinant of the source matrix is returned. If there is no 
inverse, scalar zero is returned. 


Remember that while an inverse may be obtained using double precision 
arithmetic, this does not necessarily mean that it can using the br_scalar,,, type. 
This difference is most marked between fixed and floating point BRender libraries. 


BrMatrix34LPInverse () ,3. 


Copyright © 1996 Argonaut Technologies Limited 


br_matrix34 


BrMatrix34LPInverse () 


Description: | Compute the inverse of the supplied length preserving’ transformation matrix. The 
resulting matrix is undefined for non-length preserving matrices. 


Equivalent to the expression: 


Declaration: void BrMatrix34LPInverse (br_matrix34* A, 
const br_matrix34* B) 


Arguments: br_matrix34 * A 
A pointer to the destination matrix (must be different from source). 
const br_matrix34 * B 
A pointer to the source matrix. 


See Also: BrMatrix34Inverse () ,.». 


BrMatrix34Apply () 


Description: | Applies a transform to a 3D point which may have non-unity homogenous co- 
ordinates. Equivalent to the expression: 


P, co P,C 
Declaration: void BrMatrix34Apply (br_vector3* A, const br_vector4* B, 
const br_matrix34* C) 
Arguments: br_vector3' * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed point. 


const br_vector4 * B 
A pointer to the source vector, holding the point to be transformed. 
const br_matrix34 * C 


A pointer to the transform matrix to be applied. 


Note that length preserving also applies to the sign of lengths, not just their magnitude, 1.e. a reflection is not 
length preserving in this case. 

+ The reason the destination vector argument isa br_vector3 and notabr_vector4, is because it is 
sometimes useful to supply a br_vector3, which would be quite invalid if the argument specified a 
br_vector4. 
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Remarks: 


(x, YB 2B wg) 


Be aware that the fourth element of the resulting vector is only implicit, and if 
required must either be copied (if the destination is actually abr_vector4,,,) or 
used to scale down the first three elements. This all depends on the purpose for 
which this function is called. 


The result in A is equivalent to the following: 
Co Cor o2 9 


Cio Ci C12 


(poo + YBCi9 + ZBl29 FWRl3q XBCO1 + VBC + ZBCa1 + Wels, XBCo2 + VeC12 F Z p20 + Wel32 {wp} 


BrMatrix34ApplyP () 


Description: 
F, 


Declaration: 


Arguments: 


Remarks: 


(x, 


Applies a transform to a 3D point. Equivalent to the expression: 

= PC 

void BrMatrix34ApplyP (br_vector3* A, const br_vector3* B, 
const br_matrix34* C) 

br_vector3 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed point. 


const br_vector3 * B 

A pointer to the source vector, holding the point to be transformed. 
const br_matrix34 * C 

A pointer to the transform matrix to be applied. 


The result in A is equivalent to the following: 


Coo Cor Con =O 


e-@ 1) Cio Cn C12 
BB 


(escoo + YBCio + Zpl00 + 30 Xplor + VBC + Zp01 +631 Xeon F YpC12 + ZpC22 + C30 i 
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BrMatrix34Applyv () 


Description: 


Declaration: 


Arguments: 


Remarks: 


(x5 YB <B 0) 


Applies a transform to a 3D vector, i.e. as for a point but without translation 
components (a vector has no location). Equivalent to the expression: 


V, <= VgC 


void BrMatrix34ApplyV (br_vector3* A, const br_vector3* B, 
const br_matrix34* C) 


br_vector3 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed vector. 


const br_vector3 * B 

A pointer to the source vector, holding the vector to be transformed. 
const br_matrix34 * C 

A pointer to the transform matrix to be applied. 


The result in A is equivalent to the following: 


Coo Cor on 9 


Cio Sin 12 


ie) 
iy 
So 
ie) 
& 
ie) 
nN 
NR 
- © © 


(xscoo + YBC10 + ZBl20 + C30 XBCor + VBC + ZpC21 + C31 XBCo2 + VBC 12 F ZBlr2 + €32 0 


BrMatrix34TApply () 


Description: 


Declaration: 


Arguments: 
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Applies a transform to a transposed 3D point which may have non-unity 
homogenous co-ordinates. Equivalent to the expression: 


P= PC’ 


void BrMatrix34TApply (br_vector4* A, const br_vector4* B, 
const br matrix34* C) 


br_vector4 * A 


A pointer to the destination vector (must be different from source), to hold the 
transformed point. 


const br_vector4 * B 


A pointer to the source vector, holding the point to be transformed. 


const br_ matrix34 * C 


A pointer to the transform matrix to be applied transposed. 


195 


br_matrix34 


Remarks: The result in A is equivalent to the following: 


Coo Cor Con 9 XB Coorg t+ CorVB t+ Co2ZB 
Cio Cy Cy O MB Vas CioXBt CyB t C22 
Co Cy) Cy ~O 2B Co9XBt Cr1VBt Co2Zp 
Cx C3, Cz 1 We C39XB + C3) VB t C39Z— + We 


BrMatrix34TApplyP () 


Description: | Applies a transposed transform to a 3D point. Equivalent to the expression: 
t 
P, — PC 
Declaration: void BrMatrix34TApplyP (br_vector3* A, const br_vector3* B, 
const br_matrix34* C) 
Arguments: br_vector3 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed point. 


const br_vector3 * B 
A pointer to the source vector, holding the point to be transformed. 
const br_matrix34 * C 


A pointer to the transform matrix to be applied transposed — the translation 
elements are presumed zero or irrelevant. 


Remarks: The result in A is equivalent to the following: 


Coo Cor Co2 9 Xp Coote + CorVet CorZB 
Cio Cy Cy O YB | —| ©10%B + CYB t Ci2zp 
Co C21 CxO ZB Co9X Bt Co1VBt Co2ZB 
- - = 1 1 1 


BrMatrix34TApplyV () 


Description: | Applies a transposed transform to a 3D vector, i.e. as for a point but without 
translation components (a vector has no location). Equivalent to the expression: 


t 
VY, = V,C 


Declaration: void BrMatrix34TApplyV (br_vector3* A, const br_vector3* B, 
const br_matrix34* C) 
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Arguments: br_vector3 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed vector. 


const br _vector3 * B 
A pointer to the source vector, holding the vector to be transformed. 
const br matrix34 * C 


A pointer to the transform matrix to be applied transposed — the translation 
elements are presumed zero or irrelevant. 


Remarks: The result in A is equivalent to the following: 


Coo Cor Cor O XB CooXB + CoB + Co2ZpB 
Cio Cy Cy O Ya | | ©10o%e + Cie t Ci22%p 
Co Cy) Cy -<O ZB Co9X Bt Co) VB t Co2ZB 
~~ Seis ee dt 0 0 


BrMatrix34Pre () 


Description: | Pre-multiply one matrix by another. Equivalent to the expression: 
A=BA 

Declaration: void BrMatrix34Pre(br_matrix34* A, const br_matrix34* B) 

Arguments: br_matrix34 * A 


A pointer to the subject matrix (may be same as B). 


const br matrix34 * B 
A pointer to the pre-multiplying matrix. 


See Also: BrMatrix34Post () ., BeMatrix34Mul () o, 


BrMatrix34PreTranslate () 


Description: | Pre-multiply a matrix by a translation transform matrix. Equivalent to the 
expression: 


M<T,,.M 


Declaration: void BrMatrix34PreTranslate(br_matrix34* mat, br_scalar dx, 
br_scalar dy, br_scalar dz) 
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Arguments: br_matrix34 * mat 

A pointer to the subject matrix. 

br_scalar dx 

‘The x axis component used to form the translation matrix. 
br_scalar dy 

‘The y axis component used to form the translation matrix. 
br_scalar dz 

The z axis component used to form the translation matrix. 


See Also: BrMatrix34PostTranslate ()., BeMatrix34Translate(),,, 


BrMatrix34PreScale () 
Description: | Pre-multiply a matrix by a scaling transform matrix. Equivalent to the expression: 


M<S,..M 


XYZ 


Declaration: void BrMatrix34PreScale(br_matrix34* mat, br_scalar sx, 
br_scalar sy, br_scalar sz) 


Arguments: br_matrix34 * mat 


A pointer to the subject matrix. 


br_scalar sx 


Scaling component along the x axis. 


br_scalar sy 


Scaling component along the y axis. 


br_scalar sz 
Scaling component along the z axis. 
See Also: BrMatrix34PostScale() ,.;, BrMatrix34Scale(),,, 


BrMatrix34PreShearx () 


Description: | Pre-multiply a matrix by an x invariant shearing transform matrix. Equivalent to the 
expression: 


M<=Z,M 


Declaration: void BrMatrix34PreShearxX (br_matrix34* mat, br_scalar sy, 
br_scalar sz) 
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Arguments: br_matrix34 * mat 
A pointer to the subject matrix. 
br_scalar sy 


Shear factor by which the x co-ordinate is included in the transformed y co- 
ordinate. 


br_scalar sz 


Shear factor by which the x co-ordinate is included in the transformed z co- 
ordinate. 


See Also: BrMatrix34PostShearxX () ,, BeMatrix34Shearx () 5, 


BrMatrix34PreShearY () 


Description: — Pre-multiply a matrix bya y invariant shearing transform matrix. Equivalent to the 
expression: 


M<_Z,M 
Declaration: void BrMatrix34PreShearY (br_matrix34* mat, br_scalar sx, 
br_ scalar sz) 
Arguments: br_matrix34 * mat 
A pointer to the subject matrix. 
br_scalar sx 


Shear factor by which the y co-ordinate is included in the transformed x co- 
ordinate. 


br_scalar sz 


Shear factor by which the y co-ordinate is included in the transformed z co- 
ordinate. 


See Also: BrMatrix34PostShearY () ,,, BrMatrix34ShearyY (),,, 


BrMatrix34PreShearZ () 


Description: — Pre-multiply a matrix by a z invariant shearing transform matrix. Equivalent to the 
expression: 


M<=Z,M 


Declaration: void BrMatrix34PreShearY (br_matrix34* mat, br scalar sx, 
br_scalar sy) 
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Arguments: 


See Also: 


br_matrix34 * mat 

A pointer to the subject matrix. 

br_scalar sx 

Shear factor by which the z co-ordinate is included in the transformed x co- 
ordinate. 

br_scalar sy 

Shear factor by which the z co-ordinate is included in the transformed y co- 
ordinate. 


BrMatrix34PostShearZ () »,, BeMatrix34ShearzZ () 5,, 


BrMatrix34PreRotate () 


Description: 


Declaration: 


Arguments: 


See Also: 


Pre-multiply a matrix by a vector specified axis, rotational transform matrix. 
Equivalent to the expression: 


MeR,M 


void BrMatrix34PreRotate (br_matrix34* mat, br_angle r, 
const br_vector3* axis) 


br_matrix34 * mat 
A pointer to the subject matrix. 
br_angle r 


The angle about the specified axis used to form the rotation matrix. A positive 
angle represents a clockwise rotation (with the vector pointing at you). 

const br_vector3* 

The arbitrary (normalised) axis vector about which the rotation occurs. 


BrMatrix34PostRotate () »,, BeMatrix34Rotate () 5), 


BrMatrix34PreRotatex () 


Description: 


Declaration: 


Arguments: 
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Pre-multiply a matrix by an x axis rotational transform matrix. Equivalent to the 
expression: 


M<=R,M 


void BrMatrix34PreRotateX (br_matrix34* mat, br_angle rx) 
br_matrix34 * mat 


A pointer to the subject matrix. 


br_angle rx 


The angle about the x axis used to form the rotation matrix. A positive angle 
represents a clockwise rotation (looking toward the origin). 
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See Also: BrMatrix34PostRotateX () »;, BeMatrix34RotateX (),,, 


BrMatrix34PreRotateY () 


Description: | Pre-multiply a matrix by a y axis, rotational transform matrix. Equivalent to the 
expression: 


M<=R,M 


Declaration: void BrMatrix34PreRotateyY (br_matrix34* mat, br_angle ry) 
Arguments: br_matrix34 * mat 

A pointer to the subject matrix. 

br_angle ry 


The angle about the y axis used to form the rotation matrix. A positive angle 
represents a clockwise rotation (looking towards the origin). 


See Also: BrMatrix34PostRotateY () »;, BeMatrix34RotateY () »); 


BrMatrix34PreRotateZ () 


Description: | Pre-multiply a matrix by a z axis, rotational transform matrix. Equivalent to the 
expression: 


M=R,M 


Declaration: void BrMatrix34PreRotateZ (br_matrix34* mat, br_angle rz) 
Arguments: br_matrix34 * mat 


A pointer to the subject matrix. 


br_angle rz 


The angle about the z axis used to form the rotation matrix. A positive angle 
represents a clockwise rotation (looking towards the origin). 


See Also: BrMatrix34PostRotateZ ()., BrMatrix34RotateZ () >); 


BrMatrix34PreTransform () 


Description: | Pre-multiply a matrix by a generic transform. Equivalent to the expression: 
M<=—M,M 


Declaration: void BrMatrix34PreTransform(br_matrix34* mat, 
const br_transform* xform) 


Copyright © 1996 Argonaut Technologies Limited 20 1 


br_matrix34 


Arguments: br_matrix34 * mat 
A pointer to the subject matrix. 
const br_transform * xform 
The pre-multiplying generic transform. 


Effects: ‘The transform is first converted to a general 3x4 transform matrix using 
BrTransformToMatrix34 (),;; and then applied as a pre-multiplying matrix 
using BrMatrix34Pre () jo. 


See Also: BrMatrix34PostTransform () 5. 


BrMatrix34Post () 


Description: | Post-multiply one matrix by another. Equivalent to the expression: 
A = AB 


Declaration: void BrMatrix34Post (br_matrix34* A, const br_matrix34* B) 
Arguments: br_matrix34 * A 
A pointer to the subject matrix (may be same as B). 
const br_matrix34 * B 
A pointer to the post-multiplying matrix. 
See Also: BrMatrix34Pre() ,.,, BrMatrix34Mul () ,o, 


BrMatrix34PostTranslate () 


Description: — Post-multiply a matrix by a translation transform matrix. Equivalent to the 
expression: 


M = MT,,. 
Declaration: void BrMatrix34PostTranslate (br_matrix34* mat, br_scalar dx, 
br_scalar dy, br_scalar dz) 
Arguments: br_matrix34 * mat 
A pointer to the subject matrix. 
br_scalar dx 


‘The x axis component used to form the translation matrix. 


br_scalar dy 


The y axis component used to form the translation matrix. 


br_scalar dz 


‘The z axis component used to form the translation matrix. 


See Also: BrMatrix34PreTranslate() ,.,, BeMatrix34Translate () 5), 
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BrMatrix34PostScale () 


Description: 


Declaration: 


Arguments: 


See Also: 


Post-multiply a matrix by a scaling transform matrix. Equivalent to the expression: 


M<MS 


XYZ 


void BrMatrix34PostScale(br_matrix34* mat, br scalar sx, 
br_scalar sy, br_scalar sz) 


br_matrix34 * mat 

A pointer to the subject matrix. 

br_scalar sx 

Scaling component along the x axis. 

br_scalar sy 

Scaling component along the y axis. 

br_scalar sz 

Scaling component along the z axis. 
BrMatrix34PreScale () ,.., BeMatrix34Scale() ,,, 


BrMatrix34PostShearx () 


Description: 


Declaration: 


Arguments: 


See Also: 


Post-multiply a matrix by an x invariant shearing transform matrix. Equivalent to 
the expression: 


M<_MZ, 


void BrMatrix34PostShearx (br_matrix34* mat, br_scalar sy, 
br_scalar sz) 


br_matrix34 * mat 
A pointer to the subject matrix. 
br_scalar sy 


Shear factor by which the x co-ordinate is included in the transformed y co- 
ordinate. 


br_scalar sz 


Shear factor by which the x co-ordinate is included in the transformed z co- 
ordinate. 


BrMat rix34PreShearX () ,.,, BeMatrix34ShearxX () ,,, 
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BrMatrix34PostShearY () 


Description: — Post-multiply a matrix bya y invariant shearing transform matrix. Equivalent to the 
expression: 


M<MZ, 


Declaration: void BrMatrix34PostShearY (br_matrix34* mat, br_scalar sx, 
br_scalar sz) 


Arguments: br_matrix34 * mat 
A pointer to the subject matrix. 
br_scalar sx 


Shear factor by which the y co-ordinate is included in the transformed x co- 
ordinate. 


br_scalar sz 


Shear factor by which the y co-ordinate is included in the transformed z co- 
ordinate. 


See Also: BrMatrix34PreShearY () ,,, BeMatrix34ShearyY (),,,; 


BrMatrix34PostShearzZ () 


Description: — Post-multiply a matrix by az invariant shearing transform matrix. Equivalent to the 
expression: 


M<€<MZ, 


Declaration: void BrMatrix34PostShearY (br_matrix34* mat, br_scalar sx, 
br_scalar sy) 


Arguments: br_matrix34 * mat 
A pointer to the subject matrix. 
br_scalar sx 


Shear factor by which the z co-ordinate is included in the transformed x co- 
ordinate. 


br_scalar sy 


Shear factor by which the z co-ordinate is included in the transformed y co- 
ordinate. 


See Also: BrMatrix34PreShearZ () ,., BrMatrix34ShearZ () 5, 
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BrMatrix34PostRotate () 


Description: | Post-multiply a matrix by a vector specified axis, rotational transform matrix. 
Equivalent to the expression: 


M = MR, 


Declaration: void BrMatrix34PostRotate (br_matrix34* mat, br_angle r, 
const br_vector3* axis) 


Arguments: br_matrix34 * mat 
A pointer to the subject matrix. 
br_angle r 


The angle about the specified axis used to form the rotation matrix. 


const br_vector3* 


The arbitrary (normalised) axis vector about which the rotation occurs. 
See Also: BrMatrix34PreRotate () .., BrMatrix34Rotate () +4, 


BrMatrix34PostRotatex () 


Description: | Post-multiply a matrix by an x axis rotational transform matrix. Equivalent to the 
expression: 


M<=MR,, 


Declaration: void BrMatrix34PostRotatexX (br_matrix34* mat, br_angle rx) 
Arguments: br_matrix34 * mat 


A pointer to the subject matrix. 


br_angle rx 


The angle about the x axis used to form the rotation matrix. A positive angle 
represents a clockwise rotation (looking towards the origin). 


See Also: BrMatrix34PreRotatexX () ., BrMatrix34RotatexX () 5, 


BrMatrix34PostRotatey () 


Description: — Post-multiply a matrix by a y axis, rotational transform matrix. Equivalent to the 
expression: 


M<=MR, 


Declaration: void BrMatrix34PostRotateY (br_matrix34* mat, br_angle ry) 
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Arguments: br_matrix34 * mat 
A pointer to the subject matrix. 
br_angle ry 


The angle about the y axis used to form the rotation matrix. A positive angle 
represents a clockwise rotation (looking towards the origin). 


See Also: BrMatrix34PreRotateY ().,, BreMatrix34RotateY () 5), 


BrMatrix34PostRotateZ () 


Description: — Post-multiply a matrix by a z axis, rotational transform matrix. Equivalent to the 
expression: 


M<=MR,, 


Declaration: void BrMatrix34PostRotateZ (br_matrix34* mat, br_angle rz) 
Arguments: br_matrix34 * mat 

A pointer to the subject matrix. 

br_angle rz 


The angle about the z axis used to form the rotation matrix. A positive angle 
represents a clockwise rotation (looking towards the origin). 


See Also: BrMatrix34PreRotateZ () »,, BeMatrix34RotateZ (),,; 


BrMatrix34PostTransform () 


Description: | Post-multiply a matrix by a generic transform. Equivalent to the expression: 


M<MM, 


Declaration: void BrMatrix34PostTransform(br_matrix34* mat, 
const br_transform* xform) 


Arguments: br_matrix34 * mat 
A pointer to the subject matrix. 
const br_transform * xform 
The post-multiplying generic transform. 


Effects: ‘The transform is first converted to a general 3x4 transform matrix using 
BrTransformToMatrix34 (),;; and then applied as a post-multiplying matrix 
using BrMatrix34Post () 1). 


See Also: BrMatrix34PreTransform() 4). 


206 Copyright © 1996 Argonaut Technologies Limited 


br_matrix34 


Conversion 


Note that only matrices can represent the full gamut of translation, shearing, reflection, and scaling 
effects, some of these effects will be lost (or produce undefined behaviour) when converting into 
another transformation. 


From Eulers, Quaternions and Transforms 


See BrEulerToMatrix34 () ,,, BrQuatToMatrix34 () »;, BrTransformToMat rix34 () 353. 


Also see BrTransformToTransform () 353. 


To Eulers, Quaternions and Transforms 
See BrMatrix34ToEuler () ,, BeMatrix34ToQuat () ,, BeMatrix34ToTransform () 5. 4s 
described below. 


Also see BrTransformToTransform () 353. 


BrMatrix34ToEuler () 


Description: | Converta3D affine matrix toa Euler angle set, that would have the same rotational 
effect. 


Declaration: br_euler* BrMatrix34ToEuler (br_euler* euler, 
const br_matrix34* mat) 


Arguments: br_euler * euler 


A pointer to the destination Euler angle set to receive the conversion. The Euler 
angle set’s Euler order is used to determine each angle. 


const br_matrix34 * mat 

A pointer to the source matrix to convert from. 
Result: br_euler * 

Returns euler for convenience. 


Remarks: — Translation components of the matrix are lost in conversion. 


BrMatrix34ToQuat () 


Description: | Convert a 3D affine matrix to a quaternion, that would have the same rotational 
effect. 


Declaration: br_quat* BrMatrix34ToQuat (br_quat* q, 
const br_matrix34* mat) 
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Arguments: 


Result: 


Remarks: 


br_quat * q 

A pointer to the destination quaternion to receive the conversion. 
const br_matrix34 * mat 

A pointer to the source matrix to convert from. 

br_quat * q 

Returns q for convenience. 


Translation components of the matrix are lost in conversion. 


BrMatrix34ToTransform () 


Description: 
Declaration: 


Arguments: 


Effects: 
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Convert a 3D affine matrix into a specific transform, that would have a similar 
transformational effect. 


void BrMatrix34ToTransform(br_transform* xform, 
const br _matrix34* mat) 


br_transform * xform 


A pointer to the destination transform. The type member of the destination 
transform is retained and determines the method of conversion. 


const br _ matrix34 * mat 


A pointer to the source matrix to be converted. 


When the transform is the identity 
The destination transform is left unchanged — no conversion necessary. 
When the transform is a translation 


The translation component of the matrix (its bottom row) is copied into the 
translation vector of the transform. 


When the transform is a Euler angle set 


Calls BrMatrix34ToEuler (), and copies the matrix’s translation component 
(its bottom row) int to the translation vector of the transform. 


When the transform is a Look-Up 


The Up vector is left unchanged and should really be set before rather than after 
this conversion. 


Copies the third row into the Look vector (if zero (0,0,0) then (0,1,0) is used 
instead). 


The matrix’s translation component is copied into the translation vector of the 
transform. 


When the transform is a quaternion 


Calls BrMat rix34ToQuat () ., and copies the matrix’s translation component (its 
bottom row) int to the translation vector of the transform. 
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When the transform is a 3x4 matrix 
Directly copies the matrix into the transform. 
When the transform is a 3x4 length preserving matrix 


Directly copies the matrix into the transform and then calls 
BrMatrix34LPNormalise () 5, 


Copy/Assign 


Although copy by structure assignment currently works, use BrMat rix34Copy () 29. or 
BrMatrix34Copy4 () . to ensure compatibility. 


BrMatrix34Copy () 
Description: | Copy a matrix. Equivalent to the expression: 
A<=B 


Declaration: void BrMatrix34Copy (br_matrix34* A, const br_matrix34* B) 
Arguments: br_matrix34 * A 


A pointer to the destination matrix (may be the same as source — though 
redundant). 


const br_matrix34 * B 


A pointer to the source matrix. 


BrMatrix34Copy4 () 


Description: | Copy a 4x4 matrix into a 3x4 matrix, discarding right-hand column. Equivalent to 
the expression: 


A<B 


Declaration: void BrMatrix34Copy4 (br_matrix34* A, const br_matrix4* B) 
Arguments: br_matrix34 * A 


A pointer to the destination matrix. 


const br_matrix4 * B 
A pointer to the source 4x4 matrix. 


See Also: BrMatrix4Copy34 () 1. 
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Access & Maintenance 


Members may be freely accessed. Maintenance is only required for length preserving matrices that 
have been modified. 


BrMatrix34LPNormalise () 


Description: | Normalise a length preserving” matrix. Equivalent to the expression: 


A, p = Norm(B_,p) 


Declaration: void BrMatrix34LPNormalise (br_matrix34* A, 
const br_matrix34* B) 


Arguments: br_matrix34 * A 
A pointer to the destination matrix, which must not point to the source matrix. 
const br_matrix34 * B 
A pointer to the source matrix. 


Effects: ‘The destination matrix is the source matrix adjusted so that it represents a length 
preserving transformation. 


Remarks: — This function is typically applied to a length preserving matrix which has 
undergone a long sequence of operations, to ensure that the final matrix is still truly 
length preserving (regardless of rounding errors). 


Referencing & Lifetime 


This structure may be freely referenced, though take care if there is potential to supply the same 
matrix as more than one argument to the same function. 


Initialisation 
No static initialisers are provided. However, four BR_VECTOR3() macros would serve as well. 


All other initialisation should use BrMat rix34Copy () 5) or any of the following initialisation 
functions. 





* Note that length preserving also applies to the sign of lengths, not just their magnitude, i.e. a reflection is not 


length preserving in this case. 
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BrMatrix34Identity () 


Description: Set the specified matrix to the identity transformation matrix. Equivalent to: 


1 0 
0 1 
0 0 
0 0 


M<eIl= 


—_—= © © 


0 


0 


0 
0 
1 


Declaration: void BrMatrix34Identity (br_matrix34* mat) 


Arguments: br_matrix34 * mat 


A pointer to the destination matrix. 


Effects: Stores the identity matrix at the destination. 


BrMatrix34Translate () 


Description: Set the specified matrix to a matrix representing a specific translation. 


Equivalent to: 


Me€T,,.= 


XYZ 


0 O 
0 O 
1 O 
8. 1 


Declaration: void BrMatrix34Translate(br_matrix34* mat, br scalar dx, 
br_scalar dy, br_scalar dz) 


Arguments: br_matrix34 * mat 


A pointer to the destination matrix. 


br_scalar dx 


Translation component along the x axis. 


br_scalar dy 


Translation component along the y axis. 


br_scalar dz 


Translation component along the z axis. 


See Also: BrMatrix34PreTranslate() ,.,, BeMatrix34PostTranslate () 4). 
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BrMatrix34Scale () 
Description: Set the specified matrix to a matrix representing a specific scaling. Equivalent to: 
. 0 0 0 
0 s, 0 0 
0 0 s. 0 
0 0 0 1 


S 


M<esS 


xyz — 


Declaration: void BrMatrix34Scale(br_matrix34* mat, br_scalar sx, 
br_scalar sy, br_scalar sz) 


Arguments: br_matrix34 * mat 


A pointer to the destination matrix. 


br_scalar sx 


Scaling component along the x axis. 


br_scalar sy 


Scaling component along the y axis. 


br_scalar sz 
Scaling component along the z axis. 


See Also: BrMatrix34PreScale () ,.., BeMatrix34PostScale () 5. 


BrMatrix34ShearxX () 


Description: Set the specified matrix to a matrix representing a shear, invariant along the x axis. 
Thus values of y and z co-ordinates will be scaled in proportion to the value of the 
x co-ordinate. Equivalent to: 


1 6 
0 1 
0 0 
0 0 


Declaration: void BrMatrix34ShearxX (br_matrix34* mat, br_scalar sy, 
br_scalar sz) 


0 
M = Z,= 2 
0 
I 
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Arguments: br_matrix34 * mat 
A pointer to the destination matrix. 
br_scalar sy 


Shear factor by which the x co-ordinate is included in the transformed y co- 
ordinate. 


br_scalar sz 


Shear factor by which the x co-ordinate is included in the transformed z co- 
ordinate. 


See Also: BrMatrix34PreShearxX () ,.., BeMatrix34PostShearxX () 43. 


BrMatrix34ShearY () 


Description: Set the specified matrix to a matrix representing a shear, invariant along the y axis. 
Thus values of x and z co-ordinates will be scaled in proportion to the value of the 
y co-ordinate. Equivalent to: 


M<_Z,= 


0 0 0 


Declaration: void BrMatrix34ShearxX (br_matrix34* mat, br_scalar sx, 
br_scalar sz) 


Arguments: br_matrix34 * mat 
A pointer to the destination matrix. 
br_scalar sx 


Shear factor by which the y co-ordinate is included in the transformed x co- 
ordinate. 


br_scalar sz 


Shear factor by which the y co-ordinate is included in the transformed z co- 
ordinate. 


See Also: BrMatrix34PreShearyY () ,, BcMatrix34PostShearY () 2. 
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BrMatrix34ShearzZ () 


Description: Set the specified matrix to a matrix representing a shear, invariant along the z axis. 
Thus values of x and y co-ordinates will be scaled in proportion to the value of the 
z co-ordinate. Equivalent to: 


ets CD SO 
a Oo So. © 


Declaration: void BrMatrix34ShearX (br_matrix34* mat, br_scalar sx, 
br_scalar sy) 


Arguments: br_matrix34 * mat 
A pointer to the destination matrix. 
br_scalar sx 


Shear factor by which the z co-ordinate is included in the transformed x co- 
ordinate. 


br_scalar sy 


Shear factor by which the z co-ordinate is included in the transformed y co- 
ordinate. 


See Also: BrMatrix34PreShearZ () ,., BeMatrix34PostShearZ () 59. 


BrMatrix34Rotatex () 


Description: Set the specified matrix to a matrix representing a rotation about the x axis though 
a specified angle. Equivalent to: 


1 0 0 O 
MER, = 0 cosO, sinOy O 
* | 0 -sinOy cos, O 

0 0 0 1 


Declaration: void BrMatrix34RotatexX (br_matrix34* mat, br_angle rx) 
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Arguments: br_matrix34 * mat 


A pointer to the destination matrix. 


br_angle rx 
Rotation about the x axis. 


See Also: BrMatrix34PreRotatexX () 5, BrMatrix34PostRotatex () »;. 


BrMatrix34RotateyY () 


Description: Set the specified matrix to a matrix representing a rotation about the y axis though 
a specified angle. Equivalent to: 


cos8, O-sin®, O 
0 1 0 O 
sin6y O cosO, O 
0 O 0 1 


Declaration: void BrMatrix34RotatexX (br_matrix34* mat, br_angle ry) 
Arguments: br_matrix34 * mat 

A pointer to the destination matrix. 

br_angle ry 

Rotation about the y axis. 


See Also: BrMatrix34PreRotateY (),, BeMatrix34PostRotateY () ,;. 


BrMatrix34RotateZ () 


Description: Set the specified matrix to a matrix representing a rotation about the z axis though 
a specified angle. Equivalent to: 


cos8, sinO, O 


0 0 1 


0 

MR, = —sinO, cos@, 0 0 
0 

0 0 O 1 


Declaration: void BrMatrix34RotateZ (br_matrix34* mat, br_angle rz) 
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Arguments: br_matrix34 * mat 


A pointer to the destination matrix. 


br_angle rz 
Rotation about the z axis. 


See Also: BrMatrix34PreRotateZ (),, BeMatrix34PostRotateZ () 296 


BrMatrix34Rotate () 


Description: Set the specified matrix to a matrix representing a rotation about a given axis vector 
though a specified angle. Equivalent to: 


M<=R, 


Declaration: void BrMatrix34Rotate (br_matrix34* mat, br_angle r, 
const br_vector3* a) 


Arguments: br_matrix34 * mat 
A pointer to the destination matrix. 
br_angle r 
Rotation about the specified axis vector. 
const br_vector3 * a 
The arbitrary (normalised) axis vector about which the rotation occurs. 


See Also: BrMatrix34PreRotate () 5, BrMatrix34PostRotate () .5. 
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br matrix4 


The Structure 


A four column, four row, scalar array, used as a 3D affine matrix for general purpose 3D 
transformations (translation, scaling, shearing, rotation). Functions are provided to allow it be used as 
though it were an integral type. It has the following form: 


Moy Mo, Moz Mo3 


Mig My, Mi M43 


It can be noted that the bottom row has a translational effect. Also note, that the matrix determinant 
represents the volume change effected. 


The typedef 

(See matrix.h for precise declaration and ordering) 

br_scalar m[4] [4] Four rows of four columns 
Related Functions 


Image Support 


See BrActorToScreenMatrix4 () ,;. 
Maths 


See BrEulerToMatrix4 () ,,,, BrQuat ToMatrix4 () ,.,, BeMatrix34Copy4 () 1». 


Related Structures 


See br_matrix34,,,, br_renderbounds_cbfn,,,. 


Members 


br_scalar m[4] [4] 


Each element of the matrix can be freely and individually accessed. 


This matrix can also be thought of as an array of four br_vector4,,, structures, e.g. br_vector4 
m[4]. Thus m[row] can be castas (br_vector4*). 
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Arithmetic 


BrMatrix4Mul () 


Multiply two matrices together and place the result in a third matrix. Equivalent to 
the expression: 


Description: 


Declaration: 
Arguments: 
Remarks: 
( 
bo 1 Pon 
by Oy Oe 
bo ba, Bap 
K bx 3, 39 


C00 + Por 10 + Po2©20 t P03¢ 


b 
b 
b 


¢ 430€00 + 931610 


See Also: 


10°00 


t+biyc 


11°10 


2000 + 921¢10 


+b 
+b 
+b 


A<—BC 


void BrMatrix4Mul (br_matrix4* A, const br_matrix4* B, 
const br _ matrix4* C) 


br_matrix4 * A 


A pointer to the destination matrix (must be different from both sources). 


const br_matrix4 * B 


Pointer to the left hand source matrix. 


const br_matrix4 * C 


Pointer to the right hand source matrix. 


The result in A is equivalent to the following: 


Dos oo 
bis C10 
bys 20 
bss 30 


12620 +B 


3229 +B 


13° 


2299 + by3¢ 


33¢ 


Ol 


30 
30 
30 


30 


“02 03 


b 
b 
b 
b 


+hoic,, +8 


0001 + Po1€11 + Po2€21 + F033; 


10601 + ers + Pi2Car FP 13¢3, 


+b,,c,,+b 


20€o1 F P21€11 + P2901 + 23634 


+b,,c,,+b 


30Co1 + P31€11 + P32€r1 + 933%, 


o0€02 t Por 12 + Por€22 t Po3¢ Dog€o3 + Pore 13 + Pore23 + 


32 0333 
Dylon FB Cy2 + B29 +1364) PygCo3 + 11613 + P1203 + 913C 55 


Doo Con + Ba1€ 19 + Ba209 + P9334) Pa9€ 03 + 21613 + P9903 + 92333 
b b 


+b +b +b +by,¢ 


3002 + 931©12 F 93299 + 933639 30€03 + 931613 + 32€03 + 933¢35 


BrMatrix4Pre34 (),., BreMatrix4PreTransform() »,; 


BrMatrix4inverse () 


Compute the inverse of the supplied 3D affine matrix. Equivalent to the 
expression: 


Description: 


Declaration: 


Arguments: 


218 


AcB'! 


br_scalar BrMatrix4Inverse(br_matrix4* A, 
const br_matrix4* B) 


br_matrix4 * A 


A pointer to the destination matrix (must be different from source). 


const br_matrix4 * B 


A pointer to the source matrix. 
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Result: br scalar 


If the inverse exists, the determinant of the source matrix is returned. If there is no 
inverse, scalar zero is returned. 


Remarks: | Remember that while an inverse may be obtained using double precision 
arithmetic, this does not necessarily mean that it can using the br_scalar,,, type. 
This difference is most marked between fixed and floating point BRender libraries. 


See Also: BrMatrix4Adjoint () »;, BeMatrix4Determinant () »,. 


BrMatrix4Apply () 


Description: | Applies a transform to a 3D point which may have non-unity homogenous co- 
ordinates. Equivalent to the expression: 


P, = P2C 


Declaration: void BrMatrix4Apply (br_vector4* A, const br_vector4* B, 
const br_matrix4* C) 


Arguments: br_vector4 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed point. 


const br_vector4 * B 


A pointer to the source vector, holding the point to be transformed. 


const br_matrix4 * C 
A pointer to the transform matrix to be applied. 


Remarks: The result in A is equivalent to the following: 


oa fig “Sq ee Se | 
%e Ye 7B eB . . aha bs 


( *Boo + YB@10 + ZB620 tWBO30 XaCo1 F YBCO + ZBC21 tM Bo31 X B02 + YBC12 + ZBC22 + Wel32 %BCO3 + YB O13 + ZpC23 F wes) 


BrMatrix4ApplyP () 


Description: | Applies a transform to a 3D point. Equivalent to the expression: 
P, = PC 


Declaration: void BrMatrix4ApplyP (br_vector4* A, const br_vector3* B, 
const br_matrix4* C) 
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Arguments: 


Remarks: 


br_vector4 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed point. 


const br_vector3 * B 


A pointer to the source vector, holding the point to be transformed. 


const br_matrix4 * C 


A pointer to the transform matrix to be applied. 


The result in A is equivalent to the following: 


foo «=—fo1 «= 02 03 


1) "10. Sidi S12, S13 


FZplo9 + C39 X Blo FY BC + ZpC21 +631 XBC02 t YwC12 F ZpC22 + C32 alos + Yatra *ZnCna + ena) 


BrMatrix4ApplyV () 


Description: 


Declaration: 


Arguments: 


Remarks: 


220 


Applies a transform to a 3D vector, i.e. as for a point but without translation 
components (a vector has no location). Equivalent to the expression: 


V, = VpC 


void BrMatrix4ApplyV(br_vector4* A, const br_vector3* B, 
const br matrix4* C) 


br_vector4 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed vector. 


const br_vector3 * B 


A pointer to the source vector, holding the vector to be transformed. 


const br_matrix4 * C 


A pointer to the transform matrix to be applied. 


The result in A is equivalent to the following: 
10. “Cat, “Cia S130’) 2 
Xz Ye Zp O = 


( peo + 'e¢10 + 29000 XpCor t Yeu FZ BC21  ¥BCo2 + Yao 12 + Zp020 Xeon + Yai +223) 
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BrMatrix4TApply () 


Description: 


Declaration: 


Arguments: 


Remarks: 


Applies a transform to a transposed 3D point which may have non-unity 
homogenous co-ordinates. Equivalent to the expression: 


t 
co PC 
void BrMatrix4TApply (br_vector4* A, const br_vector4* B, 
const br_matrix4* C) 
br_vector4 * A 


A pointer to the destination vector (must be different from source), to hold the 
transformed point. 


const br_vector4 * B 

A pointer to the source vector, holding the point to be transformed. 
const br_matrix4 * C 

A pointer to the transform matrix to be applied transposed. 


The result in A is equivalent to the following: 


Coo €or Co2 Cos XB CoorXB t+ Core + Co2ZB t+ CosWe 
Cio Cu C12 C13 YB |x| @1OME he C1aee Cig Bp 
Cr €21 Cn2 C93 2B CooX pt Co1VRBt Cy9ZpB t+ Co3WB 
C39 C31 C32 C33 Wp C30XB t+ C31 VB + C39ZpB + C33WB 


BrMatrix4TApplyP () 


Description: 


Declaration: 


Arguments: 


Applies a transposed transform to a 3D point. Equivalent to the expression: 
t 
— PC 
void BrMatrix4TApplyP (br_vector4* A, const br_vector3* B, 
const br_matrix4* C) 
br_vector4 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed point. 


const br_vector3 * B 


A pointer to the source vector, holding the point to be transformed. 


const br_matrix4 * C 


A pointer to the transform matrix to be applied transposed. 
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Remarks: The result in A is equivalent to the following: 


Coo Cor Co2 03 XB CooXB + CoB + Co2ZB + Co3 
Cio C1 C12 C13 Va Na Oto Be? Cra PC 1osp 70 3 
Co C21 C22 C93 ZB Co9X Bt CoiVBt Co2ZB + C3 
C39 C31 C32 C33 1 C39XB + C31VB t+ C32ZB + C33 


BrMatrix4TApplyv () 


Description: — Applies a transposed transform to a 3D vector, i.e. as for a point but without 
translation components (a vector has no location). Equivalent to the expression: 


t 
VA = VpC 
Declaration: void BrMatrix4TApplyV (br_vector4* A, const br_vector3* B, 
const br _matrix4* C) 
Arguments: br_vector4 * A 


A pointer to the destination vector (must be different from source, and not part of 
transform), to hold the transformed vector. 


const br_vector3 * B 

A pointer to the source vector, holding the vector to be transformed. 
const br_matrix4 * C 

A pointer to the transform matrix to be applied transposed. 


Remarks: The result in A is equivalent to the following: 


Coo Cor Co2 o3 Xp CooXp + CoB + Co2ZB 
Cio Cir C12 C13 Ve | | @10ke Seiya o12%e 
Coo C21 Co2 C93 ZB Co9XB t Co VB t Co2ZpB 
C39 «6C31 C32 C33 0 C30Xp + C31VB + C3228 


BrMatrix4Pre34 () 
Description: | Pre-multiply one matrix by another. Equivalent to the expression: 


A<BA 


Declaration: void BrMatrix4Pre34 (br_matrix4* A, const br_matrix34* B) 
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Remarks: 


See Also: 


br_matrix4 


br_matrix4 * A 

A pointer to the subject matrix (may be same as B). 
const br_matrix34 * B 

A pointer to the pre-multiplying matrix. 


The result in A is equivalent to the following: 


b 


02 409 


0 

by 9 Fig! Gris Fis “Fag 
0 
0 


Dy 499 821 gn 493 

D3 439 431 439 433 

1419 + Do2429 Doo4o1 + Poi 411 + Por, Doo4o2 + Po. 412 + P9242 D043 + P0113 + P0243 

1419 + 917459 Dydoy + O44, + Oya, B49 + O11 4 12 + O14 D943 + 1413 + Oy 9493 

1419 + By749 D941 + Oy) 4 11 + Oy 49, Dy94 92 + By, 412 + By459 9493 + 1413 + By7493 

1419 + 937499 + 439 394g, + 31411 + F32421 +431 3402 + 31412 + P3949 +432 39493 + 931413 + 32403 + 433 


BrMatrix4Mul () 5,3. 


BrMatrix4PreTransform () 


Description: 


Declaration: 


Arguments: 


Effects: 


Pre-multiply a matrix by a generic transform. Equivalent to the expression: 


M<—M,M 


void BrMatrix4PreTransform(br_matrix4* mat, 
const br_transform* xform) 


br_matrix4 * mat 

A pointer to the subject matrix. 

const br_transform * xform 
The pre-multiplying generic transform. 


The transform is first converted to a general 3x4 transform matrix using 
BrTransformToMatrix34 (),;; and then applied as a pre-multiplying matrix 
using BrMatrix4Pre34 (),,.. 


BrMatrix4Adjoint () 


Description: 


Declaration: 
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Find the adjoint of a matrix — the transposed matrix of co-factors. Equivalent to the 
expression: 


A = Adjoint(B) 


void BrMatrix4Adjoint (br_matrix4* A, const br_matrix4* B) 


223 


br_matrix4 


Arguments: br_matrix4 * A 


A pointer to the destination matrix (may be same as source). 


const br_matrix4 * B 


A pointer to the source matrix. 


See Also: BrMatrix4Inverse () 4. 


BrMatrix4Determinant () 


Description: Calculate the determinant of a matrix. Equivalent to the expression: 


Declaration: br_ scalar BrMatrix4Determinant (const br_matrix4* mat) 





Arguments: const br_matrix4 * mat 


A pointer to the source matrix. 


Result! br scalar 


The determinant of the source matrix. 


See Also: BrMatrix4Inverse () 4. 


Conversion 


From Eulers and Quaternions 


See BrEulerToMatrix4 () ,,,, BrQuat ToMatrix4 () ,,. 


To Eulers and Quaternions 


See BrMatrix4ToEuler (),,,, BreMatrix4ToQuat ().,, as described below. 


BrMatrix4ToEuler () 


Description: | Converta3D affine matrix toa Euler angle set, that would have the same rotational 
effect. 


Declaration: br_euler* BrMatrix4ToEuler(br_euler* euler, 
const br_matrix4* mat) 
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Arguments: br_euler * euler 


A pointer to the destination Euler angle set to receive the conversion. The Euler 
angle set’s Euler order is used to determine each angle. 


const br_matrix4 * mat 
A pointer to the source matrix to convert from. 
Result: br euler * 


Returns euler for convenience. 


Remarks: Translation and projective (fourth column) components of the matrix are lost in 
conversion. 


BrMatrix4ToQuat () 


Description: | Convert a 3D affine matrix to a quaternion, that would have the same rotational 
effect. 


Declaration: br_quat* BrMatrix4ToQuat (br_quat* q, const br_matrix4* mat) 
Arguments: br_quat * q 


A pointer to the destination quaternion to receive the conversion. 


const br_matrix4 * mat 


A pointer to the source matrix to convert from. 


Result! br_quat * q 


Returns q for convenience. 


Remarks: Translation and projective (fourth column) components of the matrix are lost in 
conversion. 


Copy/Assign 


Although copy by structure assignment currently works, use BrMat rix4Copy () ».; to ensure 
compatibility. 


BrMatrix4Copy () 


Description: | Copy a matrix. Equivalent to the expression: 
A<=B 


Declaration: void BrMatrix4Copy (br_matrix4* A, const br_matrix4* B) 
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Arguments: 


br_matrix4 * A 


A pointer to the destination matrix (may be the same as source — though 
redundant). 


const br_matrix4 * B 


A pointer to the source matrix. 


BrMat rix4Copy34 () 


Description: 


Declaration: 


Arguments: 


Effects: 


See Also: 


Copy a 3x4 matrix into a 4x4 matrix. Equivalent to the expression: 


A<=B 


void BrMatrix4Copy34 (br_matrix4* A, const br_matrix34* B) 
br_matrix4 * A 

A pointer to the destination matrix. 

const br_matrix34 * B 

A pointer to the source 3x4 matrix. 


The source is copied into the destination, and the fourth column of the destination 
is set to the implicit (0,0,0,1) column vector. 


BrMat rix34Copy4 () ». 


Referencing & Lifetime 


This structure may be freely referenced, though take care if there is potential to supply the same 
matrix as more than one argument to the same function. 


Initialisation 


No static initialisers are provided. However, four BR_VECTOR4() macros would serve as well. 


All other initialisation should use BrMatrix4Copy (),,; or any of the following initialisation 


functions. 
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BrMatrix4Identity () 


Description: Set the specified matrix to the identity transformation matrix. Equivalent to: 


1 0 0 
0 1 
0 0 
0 0 0 


Declaration: void BrMatrix4Identity (br_matrix4* mat) 


M<eIl= 


= © © 


0 
0 
1 


Arguments: br_matrix4 * mat 
A pointer to the destination matrix. 


Effects: Stores the identity matrix at the destination. 


BrMatrix4Scale () 
Description: Set the specified matrix to a matrix representing a specific scaling. Equivalent to: 
s. 0 0 0 
0 s, 0 
0 0 s, 
0 0 0 


Declaration: void BrMatrix4Scale(br_matrix4* mat, br_scalar sx, 
br_scalar sy, br_scalar sz) 


M<_S 


XYZ = 


0 
0 
1 


Arguments: br_matrix4 * mat 


A pointer to the destination matrix. 


br_scalar sx 


Scaling component along the x axis. 
br_scalar sy 


Scaling component along the y axis. 


br_scalar sz 


Scaling component along the z axis. 
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BrMatrix4Perspective () 


Description: 


Declaration: 


Arguments: 


Effects: 


Remarks: 


228 


1 
cots O : é 
aspect 
1 
0 cots 0 0 
M <= Perspective = 
0 0 Zyon + Zhither -1 
Zyon — “hither 
= ech Shither 
0 0 ———— _ 0 


Generate a perspective transformation matrix, that can be used to convert from a camera 
actor’s co-ordinate space into the homogenous screen space (assuming a centred 
projection). This maps the viewing volume into the rendering volume, a cuboid 
delimited by the homogenous screen co-ordinates (left, bottom, near) (-1,-1,+1) to 
(+1,+1,-1). The matrix created is equivalent to the following (a=field of view). 








Zyon — “hither 


void BrMatrix4Perspective (br_matrix4* mat, 
br_angle field_of_view, br_scalar aspect, br_scalar hither, 
br_scalar yon) 


br_matrix4 * mat 

A pointer to the destination matrix to receive the perspective transform. 
br_angle field_of_view 

Field of view, i.e. the angle subtended at the camera between the top and bottom 
of the view volume. 


br_scalar aspect 


Scaling factor for width of viewing volume, i.e. +1 in y view ordinates is mapped to 
the height of the output image, andtaspect inx view ordinates is mapped to the 
width of the output image. 


br_scalar hither 

z ordinate of front of view volume. The value should be less than zero. 
br_scalar yon 

z ordinate of back of view volume. The value should be less than hither. 
Calculates the camera to screen transformation matrix and stores it at mat. 


Note that hither and yon are of opposite sign to the comparable values of 
hither_z and yon_z that would be specified inbr_camera,,,. This is because 
they are ordinates as opposed to distances. 


Note that the front clip plane is at a homogenous screen z ordinate of -1. 
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See Also: br_camera,,, BrActorToScreenMatrix4 (),;. 
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br mode test cbfn 


‘The Call-Back Function 


This type defines a mode test function, as required by BrFileOpenRead () ¢o. 





The typedef 

(See brfile.h fora precise declaration) 

int br_mode_test_cbfn(const br_uint_8*, br_size_t) Test file’s mode 
Specification 


CBFnModeTest () 


Description: | An application defined call-back function determining the type of a file from a 
given number of characters (specified with the call-back function) from the start 
of the file. 


Declaration: int BR_CALLBACK CBFnModeTest (const br_uint_8* magics, 
br_size_t n_magics) 


Arguments: const br_uint_8 * magics 
Pointer to n_magics characters. 
br_size_t n_magics 
Number of characters pointed to. 
Effects: Interpret the characters and determine the mode of the file (or file type). 


Result: int 


If the file is binary return BR_FS_MODE_BINARY, if text return 
BR_FS_MODE_TEXT, otherwise return BR_FS_MODE_UNKNOWN. 


Copyright © 1996 Argonaut Technologies Limited 2 3 1 


br_model 


br model 


The Structure 


BRender’s model data structure, describing a mesh of triangles. 


The typedef 


(See model.h for precise declaration and ordering) 


Behaviour 
br_uint_16 flags 
br_model_custom_cbfn * custom 


Geometry 

br_vertex * vertices 
br_uint_16 nvertices 
br_face * faces 
br_uint_16 nfaces 
br_vector3 pivot 


Computed Geometry 


br_scalar radius 
br_bounds bounds 
Supplementary 

char * identifier 
void * user 
Related Functions 


Scene Rendering 


See Br[Zb|Zs ]ModelRender () 553954. 


Related Structures 


Scene Modelling 


Model flags 


A custom model call-back function 


A pointer to an array of vertices 
Number of vertices in the model 
A pointer to an array of faces 
Number of faces in the model 
Offset of model’s pivot point 


The bounding radius of the model 
The axis-aligned bounding box of the model 


Model name 
An optional user-supplied pointer 


See br_actor,,, br_material,,,, br_face,,,, br_vertex,7,. 


Scene Rendering 





See br_renderbounds_cbfn,,;, br_model_custom_cbfn,,,. 
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Members 
Behaviour 


br_uint_16 flags 


This member determines how the model’s geometry is computed. Various flags can be combined 
using the ‘Or’ operation. They’re described in the following table. 


Flag Symbol Behaviour 


BR_MODF_KEEP_ORIGINAL| Retain original vertices andfaces during model update — otherwise these are freed 
and replaced by an optimised and equivalent set (very likely reordered) 


BR_MODF_GENERATE_ TAGS | Improve update speed at the expense of face and vertex tag tables. Only use in 
conjunction with BR_MODF_KEEP_ORIGINAL 


BR_MODF_QUICK_UPDATE | Improve update speed at the expense of having models that may take longer to render 


Ww 


R_MODF_DONT_WELD Don’t eliminate redundant vertices (having identical co-ordinates) 











w 


R_MODF_CUSTOM Invoke a custom call-back for this model 


br_model_custom_cbfn * custom 


If the BR_MODF_CUSTOM flag is specified, instead of being rendered, the function pointed to by 
custom is called. This may of course then call BrZbModelRender () 553, say. See 
br_model_custom_cbfn,,,. 


Geometry 


br_vertex * vertices 


A list of vertex structures describing the model’s geometry (also containing texture co-ordinates and 
pre-lighting). The vertices can be allocated at the same time as the model, otherwise vertices 
should point to a list with a sufficient lifetime (and BR_MODF_KEEP_ORIGINAL must be set). 


br_uint_16 nvertices 


Number of vertices supplied in the list of vertices. 


br_face * faces 


A list of face structures describing the model’s surface in terms of its vertices (also containing 
smoothing information, edge flags, and materials). The faces can be allocated at the same time as the 
model, otherwise faces should point to a list with a sufficient lifetime (and 
BR_MODF_KEEP_ORIGINAL must be set). 
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br _uint_16 nfaces 


Number of faces supplied in the list of faces. 


br_vector3 pivot 


Offset from model geometry origin to model origin. Effectively an offset which is subtracted from 
each model vertex. Alternatively, it may be thought of as a vector in the model’s co-ordinate space 
defining the point at which the model attaches to its parent (assuming an identity transform). 


This member is provided to facilitate centring geometry (thus not needing to modify vertex data), 
and thus enables such things as tighter bounding radii. It is not really intended to supplement the 
model actor transform, i.e. as another way of translating models. 


Computed Geometry 


br scalar radius 


‘The maximum vertex length, thus the radius defining the smallest origin centred sphere enclosing 
the model. This is computed upon BrModelAdd (),,. and when the BR_MODU_RADIUS flag is 
specified to BrModelUpdate () 5,). 


br_bounds bounds 


The minimum and maximum x,y and z ordinates of the vertices, thus the minimal, axis aligned 
(orthogonal faced) cuboid enclosing the model. This is computed upon BrModelAdd () 54) and when 
the BR_MODU_BOUNDING_BOx flag is specified to BrModelUpdate () 54). 


Supplementary 


char * identifier 


Pointer to unique, zero terminated, character string (or NULL if not required). Can be used as a handle 
to retrieve a pointer to the model. Not intended for intensive use. Typically used to collect pointers 
to models loaded using BrModelLoad () 5,, and added to the registry using BrModelAdd () 449. Also 
ideal for diagnostic purposes. 


A non-unique string can be supplied, but which of a set of models having the same string will be 
matched by search functions (See BrModelFind () ,,,), is undefined. Also in consideration of 
searching, it is not recommended that non-alphabetic characters are used, especially Slash (‘/’), 
Asterisk (‘*’), and Query (‘?’), which are used for pattern matching. 


This member can be modified by the programmer at any time. 


If identifier is set by BrModelLoad () ,,, or BeModelLoadMany () 5,, it will have been 
constructed using BrResStrDup () 4». 
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void * user 


br_model 


A member whose usage is entirely application dependent. It can be useful when writing custom 
model rendering functions (see br_model_custom_cbfn,,,). 


Operations 


BrModelPick2D () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


Casts a ray into a model and calls a call-back for all faces that intersect the ray. 
This can be used in conjunction with BrScenePick2D () ., to give face/edge/ 
vertex picking. 

int BrModelPick2D (br_model* model, 

const br_material* material, const br_vector3* ray pos, 
const br_vector3* ray dir, br_scalar t_near, 

br_scalar t_far, br_modelpick2d_cbfn* callback, void* arg) 


br_model * model 

Non-NULL pointer to model. 

const br_material * material 
Non-NULL pointer to model’s default material. 


const br_vector3 * ray pos 





Non-NULL pointer to a 3D vector giving a starting position of a pick ray in the 
model’s co-ordinate space. 


const br_vector3 * ray dir 

Non-NULL pointer to a 3D vector giving the direction of the pick ray. 
br_scalar t_near, t_far 

Coefficients of ray_dir defining the section of the ray that should be 


considered. Intersections outside this section are ignored. t_near should be 
less than t_far. 


br_modelpick2d_cbfn * callback 


Non-NULL pointer to call-back function to be called for each face intersecting 
the specified ray section. 


void * arg 
An optional argument to pass to the call-back function. 


Between BrBegin () ,, and BrEnd() ,,. BRender has completed initialisation. 
The specified model and material have been updated. 


The model’s geometry is scanned to find faces that intersect the specified ray 
section. The supplied call-back is called for each intersecting face. 
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Result: int 


If the call-back returns a non-zero value, traversal halts and that value is 
returned. Otherwise, zero is returned. 


Remarks: — This function is typically used within BrScenePick2D () ,, to refine selection 


further down to the face level. Perspective texture co-ordinates are also 
available to provide such things as 3D texture editing, or surface controls. 


Example: The following code gives an example of call-backs that enable changing the 
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material assigned to a face of a (non-inherited) model under a particular screen 
pixel. 


int BR_CALLBACK MyPickNearestModelCallback (br_model* model, const 
br_material* material, const br_vector3* ray_pos, const 
br_vector3* ray_dir, br_scalar t, int f,int e, int v, const 
br_vector3* p, const br_vector2* map, my_pick_nearest* pn) 


{ if (t<pn->t)/* has its own model & nearer */ 

{ pn->t=t; 
pn->actor=pn->temp_actor; 
pn->model=model; 
pn->material=material; 
pn->point=*p; 
pn->face=f; 
pn->edge=e; 
pn->vertex=v; 
pn->map=*map; 

} 


return 0; 


/* Test callback */ 

int BR_CALLBACK MyPickNearestCallback (br_actor* actor, const 
br_model* model, const br_material* material, const br_vector3* 
ray_pos, const br_vector3* ray_dir, br_scalar t_near, 
br_scalar t_far, my_pick_nearest* pn) 

{ pn->temp_actor=actor; 
if (actor->model) 


BrModelPick2D(actor->model, material, ray_pos, ray_dir, 
t_near, t_far, MyPickNearestModelCallback, pn); 


return 0; 


BrScenePick2D(test_world, observer, back_buffer, PickCursor_X, 
PickCursor_Y, MyPickNearestCallback, &PickNearest) ; 


if (PickNearest.model) 


{ PickNearest.model- 
>faces [PickNearest.face] .material=pick_material; 


BrModelUpdate(PickNearest.model,BR_MODU_ALL) ; 
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See Also: 


BrModelApplyMap () 


BrScenePick2D () g, 


br_model 


Generate texture co-ordinates (u,v) for a model’s vertices, using a planar, 


spherical, cylindrical, disc or null mapping. The model’s vertices can be pre- 


void BrModelApplyMap (br_model* model, 


int map_type, 


Description: 

transformed by an optional matrix. 
Declaration: 

const br_matrix34* xform) 
Arguments: br_model * model 


A pointer to a model. 


int map_type 


Mapping type. This determines how a texture is wrapped around a model. Each 
type is described in the following table. 


Map Type Symbol 


BR_APPLYMAP_NONE 


BR_APPLYMAP_PLANE 


[AP_DISC 


IAP_CYLINDER 























IAP_SPHERE 





Mapping 


None 


Planar 


Disc 


Cylindrical 


Spherical 





Texture Co-ordinates (u,v) 


(0 0) 
G(x+1) 3(y+ 1) 
(;;arctan= Lear) 
(;,arctan= s(y + 1)) 
( .aretan2 [= arctan) 
+2 


The disc mapping can be visualised by considering a cylindrical mapping, but 
shrinking one end of the cylinder to a point and then flattening it to form a disc. 


The cylindrical mapping, predictably, can be visualised by imagining a texture 
wrapped around the outside ofa cylinder. The spherical mapping is similar toa 
cylindrical mapping, but the ends of the cylinder are shrunk to single points. 


const br matrix34 * xform 


A pointer to an optional matrix. If NULL, the identity transformation 1s used. 


See Also: 


BrModelFitMap () 53. 
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BrModelFitMap () 


Description: 


Declaration: 


Arguments: 


Result: 


See Also: 


Generate a transformation which will map the bounds of a model onto a cube 
defined by the corner co-ordinates (-1,-1,-1) and (1,1,1). When passed to 
BrModelApplyMap (),,;, texture co-ordinates will be generated which fit the 
model exactly. The two axes along which the mapping is applied must be 
specified. 


br_matrix34* BrModelFitMap (const br_model* model, 
int axis_0, int axis_1, br_matrix34* transform) 


const br_model * model 
A pointer to a model. 
int axis_0, axis_1l 


Mapping axes, defined as follows: 


Mapping Axis Mapping is Applied 
Symbol Along 
BR_FITMAP_PLUS_X Positive x axis 
BR_FITMAP_PLUS_Y Positive y axis 
BR_FITMAP_PLUS_Z Positive z axis 
BR_FITMAP_MINUS_X Negative x axis 
BR_FITMAP_MINUS_Y Negative y axis 
BR_FITMAP_MINUS_Z Negative z axis 























br_matrix34 * transform 
A pointer to the destination transformation matrix. 
br_matrix34 * 


Returns a pointer to the destination transformation matrix as supplied (for 
convenience). 


BrModelApplyMap () »;; 


BrSceneModelLight () 


Description: 


Declaration: 
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Generate prelit lighting values for the vertices of a given model, using the 
current rendering’s lighting set-up. 

void BrSceneModelLight (br_model* model, 

const br_material* default_material, const br_actor* root, 
const br_actor* a) 
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Arguments: br_model * model 


Non-NULL pointer to model to calculate prelit values for. 


const br_material * default_material 





Non-NULL pointer to default material to use for model. 


const br_actor* root 


Pointer to root actor of scene, e.g. as supplied to 
BrZbSceneRenderBegin () ,;. If this function is called from within a custom 
model call-back, NULL may be used to indicate that the root effective for the 
current actor is to be used. 
const br_actor* a 
Pointer to actor defining the required co-ordinate space for the model to be 
prelit. If this function is called from within a custom model call-back, NULL may 
be used to indicate that the current actor should is to be used. 

Preconditions: Between BrBegin () ,) and BrEnd () ,,. Currently rendering, e.g. between 
BrZbSceneRenderBegin () ,, and BrZbSceneRenderEnd () ,.. 

Effects: | Works out lighting for the supplied model as though it were attached to the 
supplied actor. Modifies the appropriate prelit members of each vertex in 
accordance with the model and its material. 

Remarks: — Generally useful for scenes having little change in lighting. Lights may be 
enabled for the first frame, this function called to pre-light various models and 
then most or all lighting disabled for performance in subsequent frames. Note 
that each model whose vertices are so set will need a BrModelUpdate () 5, 
applied before the next rendering. 


See Also: br_vertex;7, 


Copy/Assign 


The br_model,,, structure should not be copied directly, e.g. by structure assignment. If a similar 
model is required, a new one should be allocated and pertinent members copied individually. Do not 
copy vertex and face lists by reference unless you have allocated them yourself. Care may be needed 
in copying identifier. 


Access & Maintenance 


Models must be added to the registry if they are involved in rendering a scene. They should not be 
modified during rendering. 


Models that have been added to the registry may be accessed by BRender during rendering. 


If any changes are made to models involved in rendering, they must be updated before the next 
rendering in which they are involved. 
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BrModelAdd () 


Adda model to the registry, updating it as necessary. All models must be added 
to the registry before they are subsequently involved in rendering. 


br_model* BrModelAdd(br_model* model) 


Description: 


Declaration: 


Arguments: 


Result: 


See Also: 


br_model * model 
A pointer to a model. 


br_model * 


Returns a pointer to the added model, else NULL if unsuccessful. 


BrModelUpdate () ,,,, BeModelAddMany () ,,), BeModelLoad () 5,,, 
BrModelFind () ,,,, BeModelRemove () 5,). 


BrModelAddMany () 


Description: 
Declaration: 


Arguments: 


Result: 


See Also: 
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Add a number of models to the registry, updating them as necessary. 
br_uint_32 BrModelAddMany (br_model* const* models, int n) 


br_model * const * models 


A pointer to an array of pointers to models. 


int n 


Number of models to add to the registry. 


br_uint_32 


Returns the number of models added successfully. 


BrModelUpdate () 5,,, BeModelAdd () 54), BeModelRemove () 54), 


BrModelRemoveMany () 5,5 


Copyright © 1996 Argonaut Technologies Limited 


br_model 


BrModelUpdate () 























Description: | Update a model that has changed in some respect since the previous update of 
this model (or BrMode1Add () 549). 
Declaration: void BrModelUpdate (br_model* model, br_uint_16 flags) 
Arguments: br_model * model 
A pointer to a model. 
br_uint_16 flags 
Model update flags. In general, BR_MODU_ALL should be used. However, the 
following table describes when to use more specific update flags. Note that 
flags can be combined using the ‘Or’ operation (BR_MODU_ALL is sucha 
combination of the other flags, for your convenience). 
Update Flag When to Use 
Symbol 
BR_MODU_VERTICES| Any aspect of vertices changes, including: vertex co-ordinates, the number 
of vertices, pre-lighting values, texture co-ordinates 
BR_MODU_FACES Any aspect of faces changes, including: the set of vertices used by all faces, 
a face’s vertex order, a face’s set of vertices, a face’s smoothing group or 
flags, the number of faces 
BR_MODU_MATERIAL]| A face’s material pointer changes 
S 
BR_MODU_ALL An unknown or wholesale change occurs 
See Also: BrModelAdd () 549. 


BrModelRemove () 


Description: 
Declaration: 
Arguments: 


Result: 


See Also: 


Remove a model from the registry. 

br_model* BrModelRemove (br_model* model) 
br_model * model 

A pointer to a model. 

br_model * 

Returns a pointer to the model removed. 
BrModelAdd () 5,0 
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BrModelRemoveMany () 


Description: | Remove a number of models from the registry. 


Declaration: br_uint_32 BrModelRemoveMany (br_model* const* models, 
int n) 


Arguments: br_model * const * models 
A pointer to an array of pointers to models. 
int n 
Number of models to remove from the registry. 
Result: br_uint_32 
Returns the number of models removed successfully. 
See Also: BrModelAddMany () 519 


Referencing & Lifetime 


Models may be multiply referenced. The model may be referenced by more than one model actor as 
long as its lifetime is longer than the actors that refer to them. Models must have been added to the 
registry if they will be involved in rendering. The model must be maintained while it is in the registry 
or being referenced. 


Initialisation 


The model is automatically initialised to zero by BrModelAllocate () ,,, Members should then be 
set appropriately. Re-initialisation is not recommended — destroy and reconstruct. 


Construction & Destruction 


Apart from import and platform specific functions, models should only be constructed by the 
following BRender function. Destruction should naturally be performed by the corresponding ‘free’ 
function, usually BreModelF ree () ,,. Note that a model should be removed from the registry before 
being destroyed. 
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BrModelAllocate () 


Description: 


Declaration: 


Arguments: 


Result: 


Allocate a new model. 


br_model* BrModelAllocate (const char* name, int nvertices, 
int nfaces) 


const char * name 
String to initialise the identifier member to. 
int nvertices 


Size of vertex list to allocate. This should be set to zero if maintaining the vertex 
list separately (in which case BR_MODF_KEEP_ORIGINAL should be 
immediately set in the returned structure). 


int nfaces 


Size of face list to allocate. This should be set to zero if maintaining the face list 
separately (in which case BR_MODF_KEEP_ORIGINAL should be immediately 
set in the returned structure). 


br_model * 


Returns a pointer to the new model, or NULL if unsuccessful. 


BrModelF ree () 


Description: | Deallocate a model and any associated memory. 
Declaration: void BrModelFree(br_model* m) 
Arguments: br_model * m 
A pointer to a model. 
Supplementary 


BrModelCount () 


Description: 


Declaration: 


Arguments: 


Result: 


Count the number of registered models whose names match a given search 
pattern. The search pattern can include the standard wild cards ‘*’ and ‘?’. 


br_uint_32 BrModelCount (const char* pattern) 
const char * pattern 

Search pattern. 

br_uint_32 


Returns the number of models matching the search pattern. 
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See Also: BrModelEnum() ,,,, BeModelFind () 54, 


BrModelEnum () 


Description: — Calls a call-back function for every model in the registry matching a given 
search pattern. The call-back is passed a pointer to each matching model, and 
its second argument is an optional pointer supplied by the user. The search 
pattern can include the standard wild cards ‘*’ and ‘?’. The call-back itself 
returns a br_uint_32,,, value. The enumeration will halt at any stage if the 
return value is non-zero. 


Declaration: br_uint_32 BrModelEnum(const char* pattern, 
br_model_enum_cbfn* callback, void* arg) 


Arguments: const char * pattern 


Search pattern. 

br_model_enum_cbfn * callback 

A pointer to a call-back function. 

void * arg 

An optional argument to pass to the call-back function. 
Result: br _uint_32 


Returns the first non-zero call-back return value, or zero if all matching models 
are enumerated. 


Example: 
br_uint_32 BR_CALLBACK test_callback(br_model* model, void* arg) 


{ br_uint_32 count; 


return(count); 


{ br_uint_32 enum; 


enum = BrModelEnum(“model”, &test_callback, NULL) ; 


BrModelFind () 


Description: — Find a model in the registry by name. A call-back function can be setup to be 
called if the search is unsuccessful. The search pattern can include the standard 
wild cards ‘*’ and ‘?’. 


Declaration: br_model* BrModelFind(const char* pattern) 
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Arguments: 


Result: 


See Also: 


br_model 


const char * pattern 
Search pattern. 
br_model * 


Returns a pointer to the model if found, otherwise NULL. Ifa call-back exists 
and is called, the call-back’s return value is returned. 


BrModelFindHook () 5,;, BcModelFindMany () 54; 


BrModelFindMany () 


Description: 


Declaration: 


Arguments: 


Result: 


See Also: 


Find a number of models in the registry by name. The search pattern can 
include the standard wild cards ‘*’ and ‘?’. 


br_uint_32 BrModelFindMany (const char* pattern, 
br_model** models, int max) 


const char * pattern 

Search pattern. 

br_model * * models 

A pointer to an array of pointers to models. 
int max 

Maximum number of models to find. 
br_uint_32 


Returns the number of models found. The pointer array is filled with pointers 
to the found models. 


BrModelFind () 5,,, BeModelFindHook () 5,5 


BrModelFindHook () 


Description: 


Declaration: 


Arguments: 


Effects: 


Functions to set up a call-back. 


br_model_find_cbfn* 
BrModelFindHook (br_model_find_cbfn* hook) 


br_model_ find _cbfn * hook 
A pointer to a call-back function. 


If BrModelFind () 5,, is unsuccessful and a call-back has been set up, the call- 
back is passed the search pattern as its only argument. The call-back should 
then return a pointer to a substitute or default model. 


For example, a call-back could be set up to return a default model if the desired 
model cannot be found in the registry. 


The function BrMode1FindFailedLoad () ,,, is provided and will probably 
be sufficient in many cases. 
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Result! br _model_find_cbfn * 


Returns a pointer to the old call-back function. 


Example: 
br_model BR_CALLBACK * test_callback(const char* pattern) 
{ br_model* default_model; 


return (default_model); 


{ bromodel* model; 


BrModelFindHook (&test_callback) ; 


model = BrModelFind(“non_existent_model”); 


See Also: BrModelFindFailedLoad () 54, 


BrModelFindFailedLoad () 


Description: This function is provided as a suitable function to supply to 
BrModelFindHook () 5,5. 


Declaration: br_model* BrModelFindFailedLoad (const char* name) 
Arguments: const char * name 
The name supplied to BrModel Find () 54. 


Effects: | Attempts to load the model from the filing system using name as the filename. 
Searches in current directory, if not found tries, in order, the directories listed 
in BRENDER PATH (if defined). If successful, sets this name as the 
identifier of the loaded model and adds the model to the registry. 


Result: br model * 
Returns a pointer to the model, if found, else NULL. 


Example: 
BrModelFindHook (BrModelFindFailedLoad) ; 
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Import & Export 


BrModelFileCount () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


Locate a given file and count the number of models in it. 

br_uint_32 BrModelFileCount (const char* filename, 
br_uint_16* num) 

const char * filename 

Name of the file containing the models to count. 

br_uint_16 * num 

Pointer to the variable in which to store the number of models counted in the 


file. If NULL, the file will still be located and appropriate success returned, but 
no count will be made. 


Searches for filename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). Ifa file is found, will count the number of models stored in it. 


br_uint_32 


Returns zero if the file was found (even if it is not a models file), non-zero 
otherwise. 


BrModelLoad () 


Description: 
Declaration: 


Arguments: 


Effects: 


Result: 


See Also: 
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Load a model. Note that it is not added to the registry. 
br_model* BrModelLoad(const char* filename) 
const char * filename 

Name of the file containing the model to load. 


Searches for f i lename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). 


br_model * 
Returns a pointer to the loaded model, or NULL if unsuccessful. 


BrModelLoadMany () 5,:, BrModelSave () 545, BeModelAdd () 540. 
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BrModelLoadMany () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


See Also: 


Load a number of models. Note that they are not added to the registry. 


br_uint_32 BrModelLoadMany (const char* filename, 
br_model** models, br_uint_16 num) 


const char * filename 

Name of the file containing the models to load. 
br_model ** models 

A non-NULL pointer to an array of pointers to models. 
br_uint_16 num 

Maximum number of models to load. 


Searches for filename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). 


br_uint_32 


Returns the number of models loaded successfully. The pointer array if 
supplied, is filled with pointers to the loaded models. 


See BrModelFileCount () 5,, to determine the number of models in a file. 


BrFmtASCLoad () 


Description: 


Declaration: 


Arguments: 
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Effects: 


Result: 


Import 3D studio models (geometry only). The models are neither updated nor 
registered. 


br_uint_32 BrFmtASCLoad(const char* name, 
br_model** mtable, br_uint_16 max_models) 


const char * name 
Name of the file containing the models. 
br_model ** mtable 


A pointer to an array of pointers to models, which will be filled as they are 
imported. If NULL, the models are still imported, but must be referenced 
subsequently by name. 


int max_models 
‘The maximum number of models to import. 


Searches for filename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). 


br_uint_32 


Returns the number of successfully imported models. 
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BrFmtNFF Load () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


Import a model expressed in the Neutral File Format. The model is neither 
updated nor registered. 


br_model* BrFmtNFFLoad(const char* name) 
const char * name 
Name of the file containing the model. 


Searches for £f i lename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). 


br_model * 


Returns a pointer to the imported model, or NULL if it could not be imported. 


BrModelSave () 


Description: 


Declaration: 


Arguments: 


Effects: 
Result: 


See Also: 


Save a model to a file. 


br_uint_32 BrModelSave(const char* filename, 
const br_model* model) 


const char * filename 

Name of the file to save the model to. 

const br_model * model 

A pointer to a model. 

Writes the model to a file’. 

br_uint_32 

Returns NULL if the model could not be saved. 
BrWriteModeSet () «, 





* Any existing file of the same name is overwritten. 
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BrModelSaveMany () 


Description: | Save a number of models to a file. 


Declaration: br_uint_32 BrModelSaveMany (const char* filename, 
const br_model* const* models, br_uint_16 num) 


Arguments: const char * filename 
Name of the file to save the models to. 
const br_model * const * models 


A pointer to an array of pointers to models. If NULL, all registered models are 
saved (irrespective of num). 


br_uint_16 num 
Number of models to save. 
Effects: | Writes the models toa file’. 
Result! br_uint_32 
Returns the number of models saved successfully. 


See Also: BrWriteModeSet () «, 





* Any existing file of the same name is overwritten. 
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br_model_custom_cbfn 


br model custom _cbfn 


‘The Call-Back Function 


This type defines a call-back function, primarily intended for the custom member of the 
br_model,,, structure. It enables an application to customise rendering for particular models, or to 
perform computations that require information only obtainable at the time a model is rendered. 


The typedef 


(See model.h fora precise declaration) 

void br_model_custom_cbfn(br_actor*, br_model*, const br_material*, void*, br_uint_8, 
int, const br_matrix34*, 
const br_matrix4*) Custom model renderer 





Related Functions 


Functions dedicated for use within rendering call-backs: Br[ZblZs ]ModelRender () 55354, 
BrOnScreenCheck () 5;,, BrOriginToScreenxY (),,;;, BcPointToScreenxY () 5;;, 
BrPointToScreenxXYMany () »;,, BrOriginToScreenXYZO () »,, BrPointToScreenXYZO () 557, 
BrPointToScreenXYZOMany () 553. 


Related Structures 


See br_renderbounds_cbfn,,, for a post-model rendering call-back. See 
br_primitive_cbfn,,, for a primitive insertion call-back used within the Z-Sort renderer. 


Specification 


CBFnModelCustom () 


Description: | An application defined call-back function that is called when a model (whose 
custom member defined as the address of this function) is about to be 
processed by the rendering engine. If this function does nothing, the model will 
not be rendered. The pass through equivalent would be for this function to call 
Br[Zb|Zs|ModelRender () 553954. 


Declaration: void BR_CALLBACK CBFnModelCustom(br_actor* actor, 
br_model* model, const br_material* material, 
void* render_data, br_uint_8 style, int on_screen, 
const br_matrix34* model_to_view, 
const br_matrix4* model_to_screen) 
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Arguments: 


Preconditions: 


252 


Effects: 


Remarks: 


Example: 


br_actor * actor 


Pointer to model actor referencing the model referring to this call-back. 


br_model * model 


Pointer to model referring to this call-back. 


const br_material * material 


Pointer to actor’s material if defined, or default material otherwise. 
void * render_data 
A pointer to the order table the primitives for this model would be inserted into, 


if the Z-Sort renderer is used. The value is NULL if no data is appropriate for 
the renderer, e.g. when using the Z-Buffer renderer. 


br_uint_8 style 

Actor’s rendering style, or default. BRender will not supply 
BR_RSTYLE_DEFAULT or BR_RSTYLE_NONE. 

int on_screen 

On-screen flag (see BrOnScreenCheck () 5;,). The call-back will never be 
called by BRender with the flag value OSC_REJECT. 


const br matrix34 * model_to_view 


A pointer to a matrix giving the model to view space transformation. 

const br_matrix4 * model_to_screen 

A pointer to a matrix giving the model to screen transformation. 

BRender has completed initialisation. Rendering is in progress. The model’s 
bounds intersect or are within the viewing volume. 

Behaviour is up to the application. Br[Zb|Zs]ModelRender () 5535, or any of 
the operations described for br_model_custom_cbfn,,, can be used. 


Any other BRender functions may be called from within this call-back with the 
following restrictions: 


e Don’t call any rendering functions, apart from 
Br[Zb|Zs]ModelRender () 9531954. 


e Don’t modify any light, clip-plane or camera actors. 
e Don’t access any output buffers until after rendering has completed. 
e Don’t change the environment actor. 


e For best performance, avoid adding, updating or removing registry items — 
try to do these things before rendering. 


e Do not modify the actor hierarchy 

Possible uses include: 

e Selecting models with different levels of detail according to viewer distance 
¢ Morphing models (BrModelUpdate () ,,, required) 

¢ Collision detection (not necessarily indicating the best method) 

e Labelling 


e Rendering liquids, gases, particulate, flames, smoke, etc. 
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br_renderbounds_cbfn,,;, br_primitive_cbfn,_,., 
br_pick2d_cbfn,,,,br_pick3d_cbfn,,,. 


The following functions are provided solely for use within CBFnModel1Custom (),.,, 
CBFnRenderBounds (),,,,and CBFnPrimitive () ,,,functions. Br|ZblZs]ModelRender () 45354 1S 
the equivalent of the function that would have been called had the model not specified a call-back 
(but it shouldn’t be specified as the call-back itself). Br[Zb|Zs]ModelRender () 5535, should not be 
called within CBFnRenderBounds () ,,, or CBFnPrimitive () 5,6. 


BrZbModelRender () 


Description: 


Declaration: 


Arguments: 


Render a model actor as part of the current Z-Buffer rendering. 


void BrZbModelRender (br_actor* actor, br_model* model, 
const br_material* material, br_uint_8 style, 
int on_screen, int use_custom) 


br_actor * actor 


The pointer to the model actor referencing the supplied model (must not be 
NULL). 


br_model * model 
The pointer to the model to be rendered (must not be NULL). 
const br_material * material 


A pointer to the material to use for rendering faces that don’t specify a material 
(must not be NULL). 


br_uint_8 style 

The rendering style to use for rendering the model (any defined style may be 
specified, even BR_RSTYLE_NONE). 

int on_screen 

A flag specifying whether the model is either partially or completely on-screen 


(either OSC_PARTIAL or OSC_ACCEPT). If OSC_ACCEPT is specified, even off- 
screen faces will be rendered. See BrOnScreenCheck () 54. 


int use_custom 


If non-zero, invoke the specified model’s custom call-back function. This is 
typically zero if the same model is specified. 
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BrZsModelRender () 


Description: 


Declaration: 


Arguments: 


Render a model actor as part of the current Z-Sort rendering. 


void BrZsModelRender (br_actor* actor, br_model* model, 
const br_material* material, br_order_table* order_table, 
br_uint_8 style, int on_screen, int use_custom) 


br_actor * actor 


The pointer to the model actor referencing the supplied model (must not be 
NULL). 


br_model * model 
The pointer to the model to be rendered (must not be NULL). 
const br_material * material 


A pointer to the material to use for rendering faces that don’t specify a material 
(must not be NULL). 


br_order_table * order _table 


A pointer to the order table the model’s primitives should be inserted into 
(must not be NULL). 





br_uint_8 style 

The rendering style to use for rendering the model (any defined style may be 
specified, even BR_RSTYLE_NONE). 

int on_screen 

A flag specifying whether the model is either partially or completely on-screen 


(either OSC_PARTIAL or OSC_ACCEPT). If OSC_ACCEPT 1s specified, even off- 
screen faces will be rendered. See BrOnScreenCheck () ;,. 


int use_custom 


If non-zero, invoke the specified model’s custom call-back function. This is 
typically zero if the same model is specified. 


BrOnScreenCheck () 


Description: 


Declaration: 


Arguments: 
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Check a bounding box in the model space against the view volume and any clip- 
planes. 


br_uint_8 BrOnScreenCheck (const br_bounds* bounds) 
const br_bounds * bounds 


A pointer to a br_bounds ,), structure giving the bounding box dimensions in 
the model’s co-ordinate space. 
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br_uint_8 


Returns one of the following: 


Flag Symbol} Meaning 
OSC_REJECT | The model is entirely outside the viewing volume 


OSC_PARTIAL | The model is partially within the viewing volume 





OSC_ACCEPT | The model is entirely within the viewing volume 


BrOriginToScreenxyY () 


Description: 


Declaration: 


Arguments: 


Result: 


‘Transform and project the origin in the model’s co-ordinate space onto the 
screen. 


br_uint_8 BrOriginToScreenxyY (br_vector2* screen) 
br_vector2 * screen 


A pointer to the destination vector to receive the co-ordinates of the point in 
projected screen space (See Projected screen space, page 23). Note that the 
point is not necessarily on screen, i.e. inside the bounds of the output pixel map. 


br_uint_8 


Returns zero if the point is in front of the eye (the viewing pyramid). 


BrPointToScreenxyY () 


Description: 


Declaration: 


Arguments: 


Result: 


‘Transform and project a single point in the model’s co-ordinate space onto the 
screen. 


br_uint_8 BrPointToScreenxyY (br_vector2* screen, 
const br_vector3* point) 


br_vector2 * screen 


A pointer to the destination vector to receive the co-ordinates of the point in 
projected screen space (See Projected screen space, page 23). Note that the 
point is not necessarily on screen, i.e. inside the bounds of the output pixel map. 


const br_vector3 * point 


A pointer to the source vector containing the co-ordinates of the point to 
project. 


br_uint_8 


Returns zero if the point is in front of the eye (the viewing pyramid). 
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BrPointToScreenXYMany () 


Description: ‘Transform and project a number of points in the model’s co-ordinate system 
onto the screen. 


Declaration: void BrPointToScreenXYMany (br_vector2* screens, 
const br_vector3* points, br_uint_32 npoints) 


Arguments: br_vector2 * screens 


A pointer to an array of destination vectors to receive the co-ordinates of each 
point in projected screen space (See Projected screen space, page 23). Note that 
the points are not necessarily on screen, i.e. inside the bounds of the output 
pixel map. 

const br_vector3 * points 

A pointer to an array of source vectors containing co-ordinates of points in 
model space. 

br_uint_32 npoints 

Number of points to process. 


Effects: Equivalent toa call of BrPointToScreenxyY (),;; for each screen and point 
vector. 


BrOriginToScreenxYZO () 


Description: Transform and project the origin in the model’s co-ordinate space onto the 
screen, generating x, y and z co-ordinates. If it is off-screen, it is not projected. 
Declaration: br_uint_32 BrOriginToScreenXYZO (br_vector3* screen) 
Arguments: br_vector3 * screen 
A pointer to the destination vector to receive the co-ordinates of the point in 
projected screen space (See Projected screen space, page 23). 


Effects: The origin is checked against the viewing volume. If within, the equivalent 
screen and depth buffer co-ordinates are calculated, otherwise the function has 
no effect. 


Result! br_uint_32 
If the co-ordinates have been placed in the destination vector the function 


returns zero, otherwise the origin is off-screen, in which case its out-code, made 
up from a combination of the flags in the following table is returned. 


Out-Code Flag | Flag Set When Origin 
Value Is 


OUTCODE_LEFT Outside left plane 
OUTCODE_RIGHT Outside right plane 
OUTCODE_TOP Outside top plane 
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OUTCODE_BOTTOM Outside bottom plane 
OUTCODE_HITHER Outside hither plane 
OUTCODE_YON Outside yon plane 





BrPointToScreenxXYZO () 


Description: Transform and project a point in the model’s co-ordinate space onto the screen, 
generating x, y and z co-ordinates. If it is off-screen, it is not projected. 
Declaration: br_uint_32 BrPointToScreenXYZO (br_vector3* screen, 
const br_vector3* point) 


Arguments: br_vector3 * screen 


A pointer to the destination vector to receive the co-ordinates of the point in 
projected screen space (See Projected screen space, page 23). 


const br_vector3 * point 
A pointer to the source vector. 

Effects: | The point is checked against the viewing volume. If within, the equivalent 
screen and depth buffer co-ordinates are calculated, otherwise the function has 
no effect. 


Result! br _uint_32 


If the co-ordinates have been placed in the destination vector the function 
returns zero, otherwise the point is off-screen, in which case its out-code, made 
up from a combination of the flags in the following table is returned. 


Out-Code Flag | Flag Set When Point 
Value Is 

OUTCODE_LEFT 0x01 Outside left plane 
OUTCODE_RIGHT | 0x02 Outside right plane 
OUTCODE_TOP 0x04 Outside top plane 


OUTCODE_BOTTOM | 0x08 Outside bottom plane 


OUTCODE_HITHER | 0x10 Outside hither plane 











OUTCODE_YON 0x20 Outside yon plane 


See Also: BrOriginToScreenXYZO () 556 
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BrPointToScreenXYZOMany () 


Description: 


Declaration: 


Arguments: 


258 


Effects: 


See Also: 


‘Transform and project a number of points in the model’s co-ordinate space onto 
the screen, generating a series x, y and z co-ordinates and out-codes. All those 
that are off-screen are not projected. 


void BrPointToScreenXYZOMany (br_vector3* screens, 
br_uint_32* outcodes, const br_vector3* points, 
br_uint_32 npoints) 


br_vector3 * screens 


A pointer to a list of destination vectors, each of which will receive co-ordinates 
of each point in projected screen space (See Projected screen space, page 23). 


br_uint_32 * outcodes 
A pointer to an array of out-codes for each point. If the co-ordinates have been 
placed in the corresponding destination vector the out-code will be zero, 


otherwise the point is off-screen, in which case only its out-code (see 
BrPointToScreenxXYZO () ,,7) is stored. 


const br_vector3 * points 

A pointer to an array of source vectors containing the points to be projected. 
br_uint32 npoints 

Number of points. 


Equivalent to a call of BrPoint ToScreenxXYZO(),;, for each point. Only co- 
ordinates of points in the viewing volume are written to corresponding 
elements of screens. 


BrOriginToScreenxXYZO () 556 
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br model enum cbfn 


‘The Call-Back Function 


This type defines a function, supplied to BrModelEnum () ,,,, and to be called by it for a selection of 
models. 





The typedef 

(See fwproto.h fora precise declaration) 

br_uint_32 br_model_enum_cbfn(br_model*, void*) Enumerator 
Specification 


CBFnModelEnum () 


Description: — An application defined call-back function accepting a model and an application 
supplied argument (as supplied to BeModelEnum () 5,,). 


Declaration: br_uint_32 BR_CALLBACK CBFnModelEnum(br_model* model, 
void* arg) 
Arguments: br_model * model 
One of the models selected by BrModelEnum () 54). 
void * arg 
The argument supplied to BrMode1Enum () 544. 
Preconditions: | BRender has completed initialisation. 
Effects: | Application defined. Avoid adding or removing models within this function. 
Result: br_uint_32 
Any non-zero value will terminate the enumeration and be returned by 
BrModelEnum () ,,,, Return zero to continue the enumeration. 


See Also: BrModelEnum () 5,,, BeModelFind () 54,. 
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br model find cbfn 


‘The Call-Back Function 


This type defines a function, registered with BrModelFindHook () ,,;, to be called when 
BrModelFind () ,,, of BeModelFindMany () ,,; fail to find any model. 


The typedef 


(See fwproto.h fora precise declaration) 


br_model* 


Specification 


br_model_find_cbfn(const char*) Find (when BrModelFind () fails) 


CBFnModelFind () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 
Result: 


Remarks: 


See Also: 
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An application defined call-back function used when BrModelFind () 54, or 
BrModelFindMany () 5,; fail. 

br_model* BR_CALLBACK CBFnModelFind(const char* name) 
const char * name 

The search pattern supplied to BeModel Find () 5,, or 
BrModelFindMany () ,,; that did not match any model. 

BRender has completed initialisation. No model has an identifier that 
successfully matches the search pattern. 

Application defined. 

br_model * 

Either return an existing model that is deemed appropriate for the search 


pattern, or NULL if there isn’t one. This value will be returned by 
BrModelFind () 5,, or BeModelFindMany () 5,5. 


This could either be used to supply a default model or to create a model. If 
models were created on demand, then this function could search another list of 
available models (but not yet created) and see if the pattern matched any of 
them, if it did, one of them could be registered and returned. Note that there is 
no way to supply more than one model. 


BrModelFind () ,,,, BeModelFindMany () ,,,, BeMode1lFindHook () ,,;, 
BrModelFindFailedLoad () 5,,. 
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‘The Call-Back Function 


This type defines a call-back function, which is called by BrMode1Pick2D () ,,;. It is called for each 
face of a particular model that intersects a given ray. It’s typically used to implement face picking 
functions for user interfaces. 


The typedef 


(See fwproto.h fora precise declaration) 

int br_modelpick2d_cbfn(br_model*, const br_material*, const br_vector3*, 

const br_vector3*, br_scalar, int, int, int, const br_vector3*, const br_vector2*, 
void*) Face pick 


Related Functions 


The function that invokes this call-back is BeModelPick2D () 5,5. 


For a function that calls a call-back for each model actor beneath a specific pixel, see 
BrScenePick2D () 


Related Structures 
See br_pick2d_cbfn,,, for a call-back from which this one is typically called. 


See br_model_custom_cbfn,,, for details of functions (used from within rendering call-backs) 
that can convert model co-ordinates into screen co-ordinates, e.g. BrPoint ToScreenxY () 555. 


Specification 


CBFnModelPick2D () 


Description: | An application defined call-back function that is called by 
BrModelPick2D () ,,;. It is called for each face that intersects a specific section 
of a particular ray in a model’s co-ordinate space. 


Declaration: int BR_CALLBACK CBFnModelPick2D (br_model* model, 
const br_material* material, const br_vector3* ray pos, 
const br_vector3* ray dir, br_scalar t, int face, 
int edge, int vertex, const br_vector3* p, 
const br_vector2* map, void* arg) 
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Arguments: 


Preconditions: 
Effects: 
Result: 


262 


P. 


Example: 





br_model * model 

Pointer to the model to pick from. 

const br_material * material 

Pointer to the default material attributed to the model. 


const br_vector3 * ray_pos 


Pointer to a 3D vector giving a starting position of the pick ray in the model’s 
co-ordinate space. 


const br_vector3 * ray dir 

Pointer to a 3D vector giving direction of ray from view-point through pixel in 
the model’s co-ordinate space. 

br_scalar t 

The co-efficient giving the position of the intersection of the face with the pick 
tay. The position is supplied in p. 

int face 

The index of the face intersecting the ray. See faces of br_model1,,,. 

int edge 


The index giving the edge nearest the intersection point. This is the edge from 
vertices [edge] to vertices [(edget+1) 3]. See br_face,,;. 





int vertex 


The index giving the vertex nearest the intersection point. This is the vertex 
vertices [vertex] inthe br_face,,, structure. 





const br_vector3 * p 


The position of the point at which the ray intersects the face, obtained using the 
following formula. 


= Pott d 


intersect ray intersect™ ray 


const br_vector2* map 


The texture co-ordinates of the intersection point on the face. Apply the 
(perspective correct) material’s texture map transform to obtain the row and 
column indices into the texture map. 


void * arg 

The corresponding value specified in the call of BeMode1Pick2D (),,, that 
invoked this call-back. 

The function is called from within BrModelPick2D () 35. 

Behaviour is up to the application. 

int 

Return zero to continue the search for intersecting faces, non-zero to terminate. 
A non-zero value will be returned by BrMode1Pick2D () ,,;. 

Possible uses include: 

e Face, Edge and Vertex Selection 
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See Also: br_model,,,,br_pick2d_cbfn,,,, br_pick3d_cbfn,,,. 
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br order table 


The Structure 


This is an order table used by the Z-Sort renderer. It contains a table of pointers to linked lists of 
rendering primitives. The Z depth range of the order table is divided into a number of equal intervals 
(buckets). Each primitive generated by the Z-Sort renderer 1s inserted into the appropriate list so that 
it is eventually rendered in order of depth. It is the application developer’s task to determine a 
scheme so that the scene is crudely segmented into layers of background through to foreground (with 
an order table for each layer), and any mutually depth critical faces are sorted in order. It does not 
matter in which order non-overlapping faces are drawn with respect to each other, so the trick is to 
sort only overlapping faces that need sorting, i.e. concave models, or interpenetrating models. 


There is a facility of nominating a primary order table such that all other secondary order tables are 
rendered in between its buckets. This provides a quick and easy way of progressing to the next step, 
after having a single order table, i.e. a primary order table for static features and individual order 
tables for models. 


Order tables are assigned to actors, either by default, inheritance or explicitly (see 
BrZsActorOrderTableSet () g,). 


The typedef 


(See order.h for precise declaration and ordering) 


Parameters 

br_scalar min_z Minimum s depth of range 

br_scalar max_z Maximum s depth of range 

br_scalar sort_z Depth at which order table should be sorted 
br_uint_16 size Number of buckets 

br_uint_16 type Sort type 

br_uint_32 flags Various flags 

Internal 

br_primitive ** table Order table array (of primitive linked-lists) 
br_order_table * next Next order table 

br_uint_16 visits Number of times order table has been referenced so far 
Related Functions 

Scene Modelling 


BrZsActorOrderTableSet () ., BrZsActorOrderTableGet () oo. 


Scene Rendering 


BrZsPrimitiveCallbackSet () ,,, BrZsPrimitiveBucketSelect () ;,.. 
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Related Structures 


Scene Rendering 


br_primitive,,,, br_primitive_cbfn,,;. 


Members 
Parameters 


br_scalar min_z, max_z 


Range of z depths over which to sort. Any z depths of vertices outside this range will be clamped to 
the limits. Note that the z depth values are a result of a linear mapping from camera co-ordinate space, 
of the range [-hither_z, -yon_z] tothe range [-hither_z, +yon_z]. These members are usually 
set by using the BR_ORDER_TABLE_NEW_BOUNDS or BR_ORDER_TABLE_INIT_BOUNDS flags, but can be 
set explicitly using the BrZsScreenZToDepth () ,, functions. Note that 

BrOriginToScreenxYZO (),,,, BrPoint ToScreenxYZO (),,, and 

BrPointToScreenXYZOMany () 55, return projected screen z ordinates, not depths. 








The z range (max_z—min_z) must be greater than 0.001, otherwise it will be forced to this range. 


br scalar sort_z 


‘This member defines the value of z used to determine the position at which this order 
table is in the list of order tables. This value is typically set to min_z, and may be set 
explicitly or automatically at the same time as min_z and max_z. There are flags available 
which can be used to specify how sort_z is calculated. 


Note that this member is not relevant to primary order tables. 


br_uint_16 size 


This member defines the number of intervals (buckets) that the z range is divided into. It also defines 
the number of pointers pointed to by table. 


An order table used for a single opaque convex model need only have one bucket, whereas a complex 
model actor with several child models (within the z range of the parent) might need several intervals. 
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br_uint_16 type 


How primitives are inserted into an order table, obviously depends upon their depth, but for 
primitives with more than one z value, such as lines, triangles and quads, how to arrive at a single z 
value is not a clear cut decision. Because it depends so much upon the scene and the application, it 
is left to the application to specify the way the sorting z should be obtained. The following table 
describes each type which can be specified in this member. 


Sort Type Z for Bucket Determination 


BR_SORT_FIRST_VERTEX | Arbitrary — the first vertex is as good as any 
BR_SORT_MIN The nearest vertex 
BR_SORT_MAX The furthest vertex 


BR_SORT_AVERAGE The average depth of vertices 





Broun So ELags 


At some point the z range of each order table must be set appropriately. The z range is not only used 
to determine into which buckets each primitive should be placed, but also in which order the order 
tables should be rendered. If the application knows in advance what this range can be then the z range 
can be set before rendering begins (see BrZsScreenZToDepth () ,,), otherwise various flags can be 
used to get the z range to be calculated automatically. Note that an order table is used in descendant 
order, that is, actors nearer the root of the hierarchy will see the order table first. Once the hierarchy 
has been traversed, the order tables will be sorted according to the value of sort_z, which can be set 
according to the values of min_z and max_z. The order tables will be rendered furthest first (see also 
BrZsOrderTablePrimaryEnable () 4). 


The flags are described in the following table. 


Flag Behaviour 


BR_ORDER_TABLE_LEAVE_BOUND | Z range is left unchanged (presumably preset) 
Ss 





BR_ORDER_TABLE_NEW_BOUNDS | Zrange is recalculated from the bounds of each actor that uses it, just before each 
use. Note that the order table is sorted according to the last value of sort_z. 





BR_ORDER_TABLE_INIT_BOUNDS | Z range is calculated from the bounds of the first actor that uses it (e.g. a 
BR_ACTOR_BOUNDS_CORRECT actor). 





BR_ORDER_TABLE_CONVEX Z range is ignored for bucket determination (primitives placed in first bucket, 
and not sorted), but other flags still apply for ordering the order table. 
BR_ORDER_TABLE_SORT_NEAR sort_z is set to min_z when the bounds are calculated 





BR_ORDER_TABLE_SORT_CENTRE | sort_z is set to (min_z+max_z) /2 when the bounds are calculated 

















BR_ORDER_TA 


Ww 


LE_SORT_FAR sort _z is set to max_z when the bounds are calculated 





The first three flags are mutually exclusive, as are the last three. Any one of the first three may be 
combined with the fourth, and any one of the last three. 


Bounds can be computed from the following actors: BR_LACTOR_MODEL, BR_ACTOR_BOUNDS and 
BR_ACTOR_BOUNDS_CORRECT. 


2 6 6 Copyright © 1996 Argonaut Technologies Limited 


br_order_table 


Note that when an order table’s bounds are calculated, they are always calculated from the full 
bounds of the model (or bounds data structure). Therefore, it is possible, where bounds intersect the 
boundaries of the viewing volume, for one of the order table bounds to lie outside the view space. All 
buckets are still rendered, but the buckets outside the view space will be empty (unless a custom 
primitive call-back has utilised them). 


Internal 


br_primitive ** table 


A pointer to a list of heads of linked lists of primitives. Each linked list is effectively each bucket of 
the bucket sort (per order table). This member is for internal use only. Each pointer will be NULL if 
the bucket is empty. Note that primitives are allocated from the primitive heap supplied at the start 
of rendering 


br_order_table * next 


Pointer to the next order table (next lowest min_z). NULL at end of list. Each rendering, this list is 
constructed (before drawing), and then deconstructed (after drawing). This member should only be 
non-NULL during rendering, i.e. within a rendering call-back function such as 
CBFnModelCustom (),;,;. This member is for internal use only. 


br _uint_16 visits 


This member is used to determine when to clear and initialise the order table’s z range (if required). 
This member is set to zero upon allocation and after rendering, and incremented each time it is 
referenced by an actor traversed during rendering. When zero, the order table is cleared (and if 
BR_ORDER_TABLE_INIT_BOUNDS is set, its z range calculated) when it is next referenced by an actor 
traversed during rendering. This member is for internal use only. 





Operations 


BrZsOrderTablePrimitivelInsert () 


Description: Insert a rendering primitive into an order table. 


Declaration: void 
BrZsOrderTablePrimitivelInsert (br_order_table* order_table 
, br_primitive* primitive, br_uint_16 bucket) 
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Arguments: br_order_table * order _table 


Non-NULL pointer to order table in which to insert primitive (supplied as 
argument to CBFnPrimitive () ;,,). 


br_primitive * primitive 


Non-NULL pointer to primitive to insert (supplied as argument to 
CBFnPrimitive () 3),). 


br_uint_16 bucket 


Bucket of order table in which to insert primitive (between 0 and 
order_table->size-1). See BrZsPrimitiveBucketSelect () 3). 


Preconditions: Between BrZsSceneRenderBegin () ,, & BrZsSceneRenderEnd () 3. 
Within a primitive call-back function. 


Effects: ‘The primitive is inserted into the order table in the specified bucket. 


Remarks: — This function is only provided to customise the ordering of primitives in a 
particular order table. It is not intended to permit automatic generation of 
primitives. 


Note that order tables are marked for clearing after rendering and allocation. 
Upon entry to a primitive call-back, the order table will have been cleared, and 
may already contain primitives. The state of other order tables is undefined. 


See Also: BrZsModelRender (),;,. 


BrZsOrderTablePrimaryEnable () 


Description: — Enable the use of a primary order table, between whose buckets all other order 
tables are then rendered. By default, no primary order table is enabled. 


Declaration: void 
BrZsOrderTablePrimaryEnable (br_order_table* order_table) 


Arguments: br_order_table * order_table 


A pointer to the order table to be used as the primary order table. If NULL is 
supplied, the default order table will be used. 


Preconditions: Between BrZsBegin () ,. & BrZsEnd () 49. 


Effects: ‘The Z sort renderer will use the specified order table as a primary order table, 
making other order tables secondary. All secondary order tables are rendered 
sequentially, as appropriate, between the rendering of the buckets of the 
primary order table. Secondary order tables whose sort_z lies further away 
than max_z are rendered first (in order of their sort_z). Then the furthest 
bucket of the primary order table is rendered, followed by the secondary order 
tables whose sort_z lies within that bucket (in order of their sort_z). This 
continues for each bucket of the primary order table. Finally, the secondary 
order tables whose sort_z is in front of the nearest bucket of the primary order 
table are rendered (in order of their sort_z). 
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Remarks: 


See Also: 


br_order_table 


Note that the primary order table facility only provides a relatively coarse way 
of merging the ordering of primitives (or buckets) in secondary order tables with 
those in the primary order table. Nevertheless, with a bit of care, it often gives 
satisfactory results for a wide range of scenes, with relatively straightforward 
allocation of order tables. 


BrZsOrderTablePrimaryDisable () 565. 


BrZsOrderTablePrimaryDisable () 


Description: 


Declaration: 


Preconditions: 
Effects: 


Remarks: 


See Also: 


Copy/Assign 


Disable the use of a primary order table. Note that the primary order table is 
disabled by default. 


void BrZsOrderTablePrimaryDisable() 
Between BrZsBegin () 5.5 & BrZsEnd () 49. 
Order tables are rendered sequentially in order of their sort_z. 


The simpler Z sort algorithm that this function engages, generally requires a 
deal of care and effort to ensure correct rendering order, especially in complex 
scenes. The results generally produce a more reliable ordering than with a 
primary order table, as so much more care is needed. 


BrZsOrderTablePrimaryEnable () 4,3. 


Structure assignment is not recommended. Copy members as appropriate. 


Access & Maintenance 


Members should only be modified with care during rendering. Do not modify primitives via table, 


or the linked list of order tables via next. Order tables are automatically cleared at the start of each 
rendering, but can be cleared thereafter (if required) using BrZsOrderTableClear () 46. 


BrZsOrderTableClear () 


Description: 
Declaration: 


Arguments: 


Preconditions: 
Effects: 
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Clear an order table, re-initialising its table of pointers to primitives. 
void BrZsClearOrderTable (br _order_table* order_table) 
br_order_table * order _table 

A non-NULL pointer to the order table to be cleared. 

Between BrZsBegin () 5,5 & BrZsEnd () 49. 


The series of void pointers pointed to by table are reset to NULL. Some 
private flags may be modified. 
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Remarks: — Note that order tables are marked for clearing after rendering and allocation. 
Upon entry to a primitive call-back, the order table will have been cleared, and 
may already contain primitives. Given automatic clearing, the use of this 
function is not generally required. 


See Also: BrZsActorOrderTableGet () 99. 


Referencing & Lifetime 


Order tables can be referred to any number of times by an actor (through use of 
BrZsActorOrderTableSet () .)). Order tables must be valid throughout rendering, i.e. between 
BrZsSceneRenderBegin () ,,and BrZsSceneRenderEnd () ;,. Note that primitive data is re-used 
from the primitive heap (supplied to BrZsBegin ()5,) each rendering. Therefore, it is not possible to 
incorporate primitives from an order table generated in one scene into another scene. 


There is a default order table which has 256 buckets and spans the depth of the view volume (its z 
range is set from the camera used for the rendering). It thus has just the flag 
BR_ORDER_TABLE_LEAVE_BOUNDS set. Do not attempt to modify the default order table - create your 





Own. 


Initialisation 


Allocation performs most initialisation. The only remaining initialisation required is to set the z range 
(min_z and max_z) and the z sort position (sort_z), which only needs to be done if these member 
will not be set by using flags such as BR_ORDER_TABLE_NEW_BOUNDS and 
BR_ORDER_TABLE_INIT_BOUNDS. 








Construction & Destruction 


Order tables should be constructed using BrZsOrderTableAllocate (),,. and destroyed using 
BrZsOrderTableFree () 55). 


BrZsOrderTableAllocate () 


Description: — Allocate a new order table. 


Declaration: br_order_table* BrZsOrderTableAllocate(br_uint_16 size, 
br_uint_32 flags, br_uint_16 type) 
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Arguments: 


Preconditions: 


Effects: 


Result: 


Remarks: 


See Also: 


br_order_table 


br_uint_16 size 

Number of buckets in order table (See br_uint_16 size, page 265). 
br_uint_32 flags 

Order table flags (See br_uint_32 flags, page 266). 

br_uint_16 type 

Order table type (See br_uint_16 type, page 266). 

Between BrZsBegin () 5, & BrZsEnd () 49. 


Memory can be allocated. 


Abr_order_table,,, data structure is allocated (using 

BrResAllocate () 4s, from the BR_MEMORY_RENDER_DATA memory class) and 
initialised (See br_order_table.,,,, Initialisation). The z range and sort z are 
initialised to zero. 





br_order_table * 
A pointer to the new br_order_table,,, data structure. 


Ensure min_z,max_z and sort_z are set appropriately if they will not be 
initialised automatically, i.e. if the BR_ORDER_TABLE_LEAVE_BOUNDS flag is 
set. 





BrZsOrderTableFree () 57, 


BrZsOrderTableF ree () 


Description: 
Declaration: 


Arguments: 


Preconditions: 
Effects: 


Remarks: 


See Also: 
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Free an order table. 
void BrZsOrderTableFree (br_order_table* order table) 
br_order_table * order_table 


A non-NULL pointer to an order table previously allocated using 
BrZsOrderTableAllocate () 5). 


Between BrZsBegin () 5. & BrZsEnd () 4). Not currently rendering. 
Uses BrResFree () ;, to release storage. 


Ensure that no actor is currently using the order table before using this function. 
Do not attempt to free an active order table, such as is passed as an argument to 
a rendering call-back function, e.g. CBFnPrimitive () 3). 


BrZsOrderTableAllocate () 5), BrResFree () 5). 
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br_pick2d_cbfn 


‘The Call-Back Function 


This type defines a call-back function, which is called by BrScenePick2D () ,,. It is called for each 
model actor in an actor hierarchy that is beneath a particular screen pixel (corresponding to a 
particular camera). It’s typically used to implement picking functions for user interfaces. 


The typedef 


(See fwproto.h fora precise declaration) 
int br_pick2d_cbfn(br_actor*, const br_model*, const br_material*, const br_vector3*, 


const br_vector3*, br_scalar, br_scalar, void*) 2D pick call- 
back 





Related Functions 


The function that invokes this call-back is BrScenePick2D () ¢. 


For a function that calls a call-back for each model actor whose bounds intersect a specific bounds, 
see BrScenePick3D () g,. 


Related Structures 
See br_pick3d_cbfn,,, for a similar 3D call-back. 


See br_model_custom_cbfn,,, for details of functions (used from within rendering call-backs) 
that can convert model co-ordinates into screen co-ordinates, e.g. BrPoint ToScreenXY () };5. 


Specification 


CBFnPick2D () 


Description: | An application defined call-back function that is called by 
BrScenePick2D () ,. It is called for each model actor whose bounds intersect 
the ray passing from a camera through a particular screen pixel (see 
BrScenePick2D () «). 

Declaration: int BR_CALLBACK CBFnPick2D (br_actor* a, 
const br_model* model, const br_material* material, 
const br_vector3* ray pos, const br_vector3* ray dir, 
br_scalar t_near, br_scalar t_far, void* arg) 


Arguments: br_actor * a 


Pointer to model actor whose model bounds intersect the pick ray. 
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const br_model * model 

Pointer to the model attributed to the model actor whose bounds intersect the 
pick ray (may be an inherited model). 

const br_material * material 

Pointer to the default material attributed to the model actor that may be used 
by the model (may be an inherited material). 

const br_vector3 * ray _pos 

Pointer to a 3D vector giving a starting position of the pick ray in the model’s 


co-ordinate space. This position has no special significance, i.e. it is not 
necessarily the position of the view-point. 


const br_vector3 * ray dir 
Pointer to a 3D vector giving direction of ray from view-point through pixel in 


the model’s co-ordinate space. The magnitude has no special significance, i.e. 
it is not necessarily the position of the model. 


br_scalar t_near 
The co-efficient giving the position of the entry point of the pick ray into the 


bounds of the intersecting model, in the model’s co-ordinate space. To obtain 
this position refer to the following formula. 


P. = Poking d 


entry ray near™ ray 
br_scalar t_far 


The co-efficient giving the position of the exit point of the pick ray out of the 
bounds of the intersecting model, in the model’s co-ordinate space. To obtain 
this position refer to the following formula. 


exit — com Ale tra pay 

void * arg 

The corresponding value specified in the call of BrScenePick2D () ,, that 
invoked this call-back. 


Preconditions: | BRender has completed initialisation. A model’s bounds intersect the pick ray. 
The order in which intersections are computed is undefined. 


Effects: | Behaviour is up to the application. 
Result: int 


Return zero continue the search for intersecting model actors, non-zero to 
terminate. A non-zero value will be returned by BrScenePick2D () 4g. 


Remarks: _ For borderline cases, the pick ray is defined to be such that if a model’s 
rendering would appear in the pixel then the model’s bounds will intersect the 
ray. The precise sub-pixel position of the ray is consistent, but undefined. 

Example: — Possible uses include: 

e Selection 


e Manipulation 
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See Also: br_model_custom_cbfn,,,,br_renderbounds_cbfn,,,, 
br_pick3d_cbfn,,.. 
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br_ pick3d_cbfn 


‘The Call-Back Function 


This type defines a call-back function, which is called by BrScenePick3D () ,,. It is called for each 
model actor in an actor hierarchy whose bounds intersect a given bounds with respect to a particular 
actor’s co-ordinate space. 


The typedef 


(See fwproto.h fora precise declaration) 
int br_pick3d_cbfn(br_actor*, const br_model*, const br_material*, const br_matrix34*, 
const br_bounds*, void*) 3Dpick 





Related Functions 


The function that invokes this call-back is BrScenePick3D () ,,. 


Fora function that calls a call-back for each model actor whose bounds intersect a ray from view-point 
through a particular screen pixel, see BrScenePick3D () gy. 


Related Structures 
See br_pick2d_cbfn,,, for a similar 2D call-back. 


See br_model_custom_cbfn,,, for details of functions (used from within rendering call-backs) 
that can convert model co-ordinates into screen co-ordinates, e.g. BrPoint ToScreenxyY () );;. 


Specification 


CBFnPick3D () 


Description: | An application defined call-back function that is called by 
BrScenePick3D () g,. It is called for each model actor whose bounds intersect 
a given bounds with respect to a particular actor’s co-ordinate space (see 
BrScenePick3D () ,,). 


Declaration: int BR_CALLBACK CBFnPick3D(br_actor* a, 
const br_model* model, const br_material* material, 
const br matrix34* transform, const br_bounds* bounds, 
void* arg) 
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Arguments: 


Preconditions: 


276 


Effects: 


Example: 


See Also: 


br_actor * a 


Pointer to model actor whose model bounds intersect the specified bounds. 
const br_model * model 

Pointer to model whose bounds intersect the pick ray. 

const br_material * material 

Pointer to the default material attributed to the model actor that may be used 
by the model (may be an inherited material). 

const br_matrix34 * transform 

A pointer to a matrix transforming the intersecting actor’s model co-ordinates 


into the co-ordinate space of the reference actor (as supplied to 
BrScenePick3D () ,,). 


const br_bounds * bounds 

A pointer to the original bounds (in the reference actor’s co-ordinate space). 
void * arg 

The corresponding value specified in the call of BrScenePick3D () ,, that 
invoked this call-back. 


BRender has completed initialisation. A model’s bounds intersect the bounds 
in the reference actor’s co-ordinate space. 


Behaviour is up to the application. 

Possible uses include: 

¢ Collision detection (does not necessarily indicate the best method) 
¢ Volumetric selection 


br_model_custom_cbfn,,,,br_renderbounds_cbfn,,,, 
br_pick2d_cbfn,,,. 
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The Structure 


BRender’s pixel map structure, used for texture maps, shade tables, blend tables, colour buffers and 
Z-buffers. See Image Support. Texture maps, shade tables, and blend tables being required for 
rendering materials should be maintained within the registry as necessary. 


The typedef 


(See pixelmap.h for precise declaration and ordering) 


Behaviour 
br_uint_8 type Individual pixel type 
br_uint_8 flags 


Size & Position 


br_int_16 origin_x, origin_y Local origin (centre), relative to base_x, base_y 

br_uint_16 width, height Size of pixel map (in pixels) 

Data 

void * pixels A pointer to raw pixel data 

br_int_16 row_bytes The difference in bytes between pixels at the same 
column of adjacent rows 

br_uint_16 base_x, base_y Co-ordinates of the region of pixels in use 

br_pixelmap * map A pointer to a colour map, used when pixel colours are 
indexed 

Supplementary 

char * identifier An optional name for texture maps and tables 

void * user User data (application dependent) 

void * device A device pointer, used if the pixel map originated from 
a device 

Related Functions 


Scene Rendering 


See BrZbSceneRenderBegin () ,,, BrZbSceneRender () 3). 


Image Support 


See BrPixelmapDoubleBuffer () ,,, BcPixelmapDirtyRectangleCopy () ,,, 
BrPixelmapDirtyRectangleFill () ,,, BrScenePick2D () ,. 
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Related Structures 


Scene Modelling 


See br_material,,,. 


Members 
Behaviour 


br_uint_8 type 


This member defines the type of data stored for each pixel in the pixel map. The various types have 
values defined by the following symbols: 


Pixel Map Type | Pixel Map Behaviour 

BR_PMT_INDEX_1 1 bit index into a colour map (2 colours) 

BR_PMT_INDEX_2 2 bit index into a colour map (4 colours) 

BR_PMT_INDEX_4 4 bit index into a colour map (16 colours) 

BR_PMT_INDEX_8 8 bit index into a colour map (256 colours) 

BR_PMT_RGB_555 16 bit ‘true colour’ RGB, 5 bits each colour 

BR_PMT_RGB_565 16 bit ‘true colour’ RGB, 5 bits red and blue, 6 bits green 
BR_PMT_RGB_888 24 bit ‘true colour’ RGB, 8 bits each colour 

BR_PMT_RGBX_888 | 32 bit ‘true colour’ RGB, 8 bits each colour, 8 bits unused 
BR_PMT_RGBA_888 | 32 bit ‘true colour’ RGB, 8 bits each colour with an 8 bit alpha channel 


BR_PMT_DEPTH_16 | The pixel map is used as a depth buffer with 16 bit precision 




















BR_PMT_DEPTH_32 | The pixel map is used as a depth buffer with 32 bit precision 


Pixel Map Type | 32 Bit Pixel Value Encoding First Four Bytes’ of Left Hand Pixel 
BR_PMT_INDEX_1 OOUOUUU TOU UO OU UNO UU OUND U UO OO OS Sack eek eS ee Gben Sh G-Ga oe, DRE ees 
BR_PMT_INDEX_2 OOOOOOCOUOCOUOU OU OUOUOUOU0UOUU0T TI Sa ss Maaa gata Ma ata Cae ata ea ata a ea ate aa 
BR_PMT_INDEX_4 OOODDODDODDODNDODNDODNOONNOOONOOOLGifiiii.... Lee eee Lee eee Cee eee 
BR_PMT_INDEX_8 OOUQOOU DOU OOO UU UUUUDU0UU LSI ET EASE AG Se eee OR CEPR DE ET, A PEE ES ES 
BR_PMT_RGB_555 00000000000000000rrrrrgggggbbbbb}] gggbbbbb Orrrrrgg ........ .....eee 
BR_PMT_RGB_565 0000000000000000rrrrrggggggbbbbb}] gggbbbbb rrrrrggg ........ ......e 
BR_PMT_RGB_888 00000000rrrrrrrrggggggggbbbbbbbb] bbbbbbbb gggggggg rrrrrrrr ........ 
BR_PMT_RGBX_888 | 00000000rrrrrrrrggggggggbbbbbbbb]| bbbbbbbb gggggggg rrrrrrrr xxXxXxXXxXXX 
BR_PMT_RGBA_8888] aaaaaaaarrrrrrrrggggggggbbbbbbbb| bbbbbbbb gggggggg rrrrrrrr aaaaaaaa 
BR_PMT_DEPTH_16 | dddddddddddddddd0000000000000000} Undefined 

BR_PMT_DEPTH_32 | dddddddddddddddddddddddddddddddd]} Undefined 











* The left hand byte is the byte at pixels. 
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All values are written with the most significant bit to the left. 


The Encoding column represents the 32 bit value to be supplied as colour to functions such as 
BrPixelmapPixelSet (),,,. The last column shows how the first pixel on a row will appear in the 
first four bytes indexed from pixels. The dots represent further pixels. The ordering of bytes pixel 
maps is independent of word byte order, except in the case of depth buffers, in which pixels are read 
and written as 32 bit values. This means that in a 16 bit depth buffer the least significant 16 bits are 
lost. 


Note, with respect to pixel maps used as textures, that zero pixels (irrespective of any palette 
information) are not rendered, and so have the effect of transparency. This only applies to textures 
and not to pixel map operations such as BrPixelmapCopy () 5. 


be dint. lags 


This is a read-only member, set upon allocation, that contains various flag values. One of the flags 
that may be useful is BR_BMF_NO_ACCESS which will be set if the pixel data is stored at pixels. If 
not set then pixels is invalid and there is no direct access to pixel data. 


Size & Position 


breint 16 -oOriginux,. origin + 


These members define the position of the co-ordinate origin of the pixel map relative to the base 
origin (given by base_x, base_y). Thusa point plotted at (0,0) will be plotted at column origin_x 
from base_x. The co-ordinate origin also effectively defines the centre of projection when used as 
a rendering destination. 


br_uint_16 width, height 


‘These members contain the dimensions of the visible region of the pixel map. 
Data 


void * pixels 


When pixel data is directly accessible (see flags), this member points to an area of memory 
containing the raw pixel data. It either points to the start of the memory occupied by the pixel map 
or the last row_bytes of it. However, it always points to the byte of the left hand pixel of the ‘first’ 
row. For instance, in monochrome pixel maps it will point to the byte whose most significant bit 
represents the left hand pixel of the first row. In true colour pixel maps it will point to the least 
significant byte of the colour of the left hand pixel of the first row, which will be the blue component 
in BR_PMT_RGB_888 pixel maps and the alpha component in BR_PMT_RGBA_8888 pixel maps. 
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br_int_16 row_bytes 

‘This member defines the physical row length of the pixel map in terms of the byte difference 
between pixels in the same column of adjacent rows. It will be negative if the pixel map memory is 
inverted. 

br_uint_16 base_x, base_y 

These members define the top left of the start of pixel map data in terms of base_y asa number of 


row_bytes, and base_x asa smaller offset from this. 


br_pixelmap * map 





For indexed pixel maps (of type BR_PMT_INDEX_?), this member points to a colour map. This is 
used to obtain the ‘true colour’ corresponding to a particular index. 


Supplementary 


char * identifier 


Pointer to unique, zero terminated, character string (or NULL if not required). 


If the pixel map is loaded or imported, the identifier will have been set using BrResSt rDup () 49. 


VOL, * User 

This member may be used by the application for its own purposes. It is initialised to NULL upon 
allocation (if allocated by BRender), and not accessed by BRender thereafter. 

void * device 


Some platform specific functions can return a pixel map structure corresponding to an area of video 
memory or other hardware. This member enables pixel map functions to determine whether the pixel 
map is in memory or not. It should not be used by the application. 
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Operations 


BrPixelmapFill () 


Description: _ Filla pixel map with a given value. 
Declaration: void BrPixelmapFill(br_pixelmap* dat, br_uint_32 colour) 
Arguments: br_pixelmap * dat 

A pointer to the pixel map to be filled. 

br_uint_32 colour 


Value to set each pixel to. 


BrPixelmapRectangleFill () 


Description: Fill a rectangular window in a pixel map with a given value. 


Declaration: void BrPixelmapRectangleFill (br_pixelmap* dst, 
br_int_16 x, br_int_16 y, br_uint_16 w, br_uint_16 h, 
br_uint_32 colour) 


Arguments: br_pixelmap * dst 
A pointer to the destination pixel map. 
br_int_16 x,y 
Co-ordinates of the rectangle’s top left corner. 
br_uint_16 w,h 
Rectangle width and height (in pixels). 
br_uint_32 colour 
Value to set each pixel to. 


Example: 
br_int_16 x,y; 
br_uint_16 w,h; 


br_pixelmap *offscreen; 


BrPixelmapRectangleFill(offscreen,x,y,w,h,0); 


BrPixelmapLine () 


Description: Draw a line ina pixel map between (xl,y1) and (x2,y2), clipping it to the edges 
of the pixel map if necessary. 
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Declaration: void BrPixelmapLine (br_pixelmap* dst, br_int_16 x1, 
br_int_16 yl, br_int_16 x2, br_int_16 y2, 
br_uint_32 colour) 


Arguments: br_pixelmap * dst 
A pointer to the destination pixel map. 
br_int_16 x1,y1,x2,y2 
Co-ordinates of the line’s endpoints. 
br_uint_32 colour 


Value to set each pixel in the line to. 


BrPixelmapPixelSet () 


Description: | Set a pixel to a given value. 


Declaration: void BrPixelmapPixelSet (br_pixelmap* dst, br_int_16 x, 
br_int_16 y, br_uint_32 colour) 


Arguments: br_pixelmap * dst 
A pointer to the destination pixel map. 
br_int_16 x,y 
Pixel co-ordinates. 
br_uint_32 colour 


Pixel value. 


BrPixelmapPixelGet () 


Description: | Get the value of a particular pixel 


Declaration: br_uint_32 BrPixelmapPixelGet (const br_pixelmap* src, 
br_int_16 x, br_int_16 y) 


Arguments: const br_pixelmap * src 
A pointer to the source pixel map from which to read the pixel. 
br_int_16 x,y 
Pixel co-ordinates. 
Result! br_uint_32 colour 
Pixel value. If the point is off-screen, zero will be returned. 


Remarks: Some device oriented pixel maps may not support read operations. 
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BrPixelmapText () 


Description: Write a string into a pixel map in a given font. 


Declaration: void BrPixelmapText (br_pixelmap* dst, br_int_16 x, 
br_int_16 y, br_uint_32 colour, const br_font* font, 
const char* text) 


Arguments: br_pixelmap * dst 
A pointer to the destination pixel map. 
br_int_16 x,y 
Co-ordinates of text’s top left corner. 
br_uint_32 colour 
Value to set each text pixel to. 
const br_font * font 
A pointer to a BRender font, or NULL for the default font. 
The following pointers are available: 
BrFontFixed3x5 
BrFontProp4x6 
BrFontProp7x9 
See brfont.h for precise declaration. 
const char * text 
A string. 

Example: 


bri uint 32 colour; 


br_pixelmap *pmap; 


BrPixelmapText (pmap, 0,0, colour, BrFontProp7x9,”Example text...”); 


BrPixelmapTextF () 


Description: | Write a ‘printf’ formatted string into a pixel map in a given font. The 
function will accept format strings and arguments just as for the standard 
printf () function. 


Declaration: void BrPixelmapTextF (br_pixelmap* dst, br_int_16 x, 
br_int_16 y, br_uint_32 colour, const br_font* font, 
const char* fmt, ...) 
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Arguments: 


Example: 


br_pixelmap * dst 

A pointer to the destination pixel map. 
br_int_16 x, y 

Co-ordinates of text’s top left corner. 
br_uint_32 colour 


Value to set each text pixel to. 


const br_font * font 


A pointer to a BRender font, or NULL for the default font. 
The following pointers are available: 
BrFontFixed3x5 


BrFontProp4x6 





BrFontProp7x9 


See brfont.h for precise declaration. 
const char * fmt 


A format string (as for printf ()). 


br uint_32 colour; 


br_pixelmap *pmap; 


BrPixelmapTextF 


( 


, 


i 


pmap,0,0,255,NULL,"Frames/Sec = %16g Polys/Sec = %16g" 
TIMING_FRAMES/ ((end_time-start_time) / (double) CLOCK_RATE) 
total_faces/ ((end_time-start_time) / (double) CLOCK_RATE) 


BrPixelmapTextWidth () 


Description: 


Declaration: 


Arguments: 


284 


Find the width of a string for a given font and pixel map. 


br_uint_16 BrPixelmapTextWidth (const br_pixelmap* dst, 
const br_font* font, const char* text) 


const br_pixelmap * dst 


A pointer to a pixel map. 


const br_font * font 


A pointer to a BRender font, or NULL for the default font. 


const char * text 


A string. 
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See Also: 


br_pixelmap 


br_uint_16 


Returns the string width in pixels. Ifthe text argument is NULL, the width of 
one character is returned. 


BrPixelmapText () 5; 


BrPixelmapTextHeight () 


Description: 


Declaration: 


Arguments: 


Result: 
See Also: 


Copy/Assign 


Find the height of a font for a given pixel map. 


br_uint_16 BrPixelmapTextHeight (const br_pixelmap* dst, 
const br_font* font) 


const br_pixelmap * dst 

A pointer to a pixel map. 

const br_font * font 

A pointer to a BRender font, or NULL for the default font. 
Returns the font height in pixels. 


BrPixelmapText () 5; 


The br_pixelmap,,, structure should not be copied by structure assignment. Copies should only be 
made via construction. However, the pixels may be copied, in whole or in part using the following 


functions. 


BrPixelmapCopy () 


Description: 


Declaration: 


Arguments: 


Example: 


Copy the data in one pixel map to another. The source and destination pixel 
maps must have the same type and dimensions. 


void BrPixelmapCopy (br_pixelmap* dst, 
const br_pixelmap* src) 


br_pixelmap * dst 
A pointer to the destination pixel map. 
const br_pixelmap * src 


A pointer to the source pixel map. 


br_pixelmap *offscreen, *backdrop; 


BrPixelmapCopy (offscreen, backdrop) ; 
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BrPixelmapRectangleCopy () 


Description: | Copy a rectangular window from one pixel map to another. 


Declaration: void BrPixelmapRectangleCopy (br_pixelmap* dst, 
br_int_16 dx, br_int_16 dy, const br_pixelmap* src, 
br_int_16 sx, br_int_16 sy, br_uint_16 w, br_uint_16 h) 


Arguments: br_pixelmap * dst 
A pointer to the destination pixel map. 
br_int_16 dx,dy 
Co-ordinates of the destination rectangle’s top left corner. 
const br_pixelmap * src 
A pointer to the source pixel map. 
br_int_16 sx,sy 
Co-ordinates of the source rectangle’s top left corner. 
br_uint_16 w,h 


Rectangle width and height (in pixels). 


Access & Maintenance 


Colour or texture maps and shade tables must be added to the registry if they are involved in 
rendering a scene. They should not be modified during rendering. 


Colour maps and shade tables that have been added to the registry may be accessed by BRender 
during rendering. 


If any changes are made to colour maps or shade tables involved in rendering, they must be updated 
before the next rendering in which they are involved. 


Note that while texture maps and shade tables are pixel maps, the reverse does not apply. A pixel 

map is only a texture map by virtue of being added to the registry as such. Similarly with a shade table. 
Most importantly, a pixel map cannot be both! A texture map must be removed from the registry for 
it to become just a pixel map, and only then could it be added as a shade table. The same applies with 
roles interchanged. Note that this just applies to the instance of the br_pixelmap,,, data structure, 
not to the memory that holds the pixel data. Therefore it is quite valid to have a texture map and 

shade table sharing the same pixel memory (not that it is easy to envisage a useful effect of doing so). 


BrMapAdd () 


Description: | Adda texture map to the registry, updating it as necessary. All texture maps 
must be added to the registry before they are subsequently involved in 
rendering. 
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Declaration: 


Arguments: 


Result: 


See Also: 


br_pixelmap 


br_pixelmap* BrMapAdd(br_pixelmap* pixelmap) 
br_pixelmap * pixelmap 

A pointer to a texture map. 

br_pixelmap * 

Returns a pointer to the added texture map, else NULL if unsuccessful. 


BrMapUpdate () 5.,, BrMapAddMany () ,.7, BrePixelmapLoad () 3), 
BrMapF ind () 5);, BeMapRemove () 53. 


BrMapAddMany () 


Description: 


Declaration: 


Arguments: 


Result: 


See Also: 


Add a number of texture maps to the registry, updating them as necessary. 


br_uint_32 BrMapAddMany (br_pixelmap* const* pixelmaps, 
int n) 


br_pixelmap * const * pixelmaps 

A pointer to an array of pointers to texture maps. 

int n 

Number of texture maps to add to the registry. 
br_uint_32 

Returns the number of texture maps added successfully. 


BrMapUpdate () ,.,, BrMapAdd () ,.,, BeMapRemove () 52, 
BrMapRemoveMany () 5. 


BrMapUpdate () 


Description: 
Declaration: 


Arguments: 


See Also: 


Update a texture map. 

void BrMapUpdate (br_pixelmap* pixelmap, br_uint_16 flags) 
br_pixelmap * pixelmap 

A pointer to a texture map. 

br_uint_16 flags 

‘Texture map update flags. In general, BR_MAPU_ALL should be used. 
BrMapAdd () 547. 


BrMapRemove () 


Description: 


Declaration: 
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Remove a texture map from the registry. 


br_pixelmap* BrMapRemove (br_pixelmap* pixelmap) 
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Arguments: br_pixelmap * pixelmap 
A pointer to a texture map. 
Result: br_pixelmap * 
Returns a pointer to the item removed. 
See Also: BrMapAdd () »., 


BrMapRemoveMany () 


Description: | Remove a number of texture maps from the registry. 


Declaration: br_uint_32 BrMapRemoveMany (br_pixelmap* const* pixelmaps, 
int n) 


Arguments: br_pixelmap * const * pixelmaps 
A pointer to an array of pointers to texture maps. 
int n 
Number of texture maps to remove from the registry. 
Result: br _uint_32 
Returns the number of texture maps removed successfully. 


See Also: BrMapAddMany () 5.7 


BrTableAdd () 


Description: | Adda shade table to the registry, updating it as necessary. All shade tables must 
be added to the registry before they are used subsequently. 


Declaration: br_pixelmap* BrTableAdd(br_pixelmap* pixelmap) 
Arguments: br_pixelmap * pixelmap 
A pointer to a shade table. 
Result: br _pixelmap * 
Returns a pointer to the added shade table, else NULL if unsuccessful. 


See Also: BrTableUpdate (),,., BrTableAddMany () 5), BcPixelmapLoad () 3), 
BrTableFind () 5.., BreTableRemove () 5.5 


BrTableAddMany () 


Description: | Adda number of shade tables to the registry, updating them as necessary. 


Declaration: br_uint_32 BrTableAddMany (br_pixelmap* const* pixelmaps, 
int n) 
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Arguments: br_pixelmap * const * pixelmaps 
A pointer to an array of pointers to shade tables. 
int n 
Number of shade tables to add to the registry. 
Result! br _uint_32 
Returns the number of shade tables added successfully. 


See Also: BrTableUpdate () ,,,, BrTableAdd () 5.., BreTableRemove () 59, 
BrTableRemoveMany () 50) 


BrTableUpdate () 


Description: | Update a shade table. 


Declaration: void BrTableUpdate (br_pixelmap* pixelmap, 
br_uint_16 flags) 


Arguments: br_pixelmap * pixelmap 
A pointer to a shade table. 
br_uint_16 flags 
Shade table update flags. In general, BR_TABU_ALL should be used. 
See Also: BrTableAdd () 49. 


BrTableRemove () 


Description: | Remove a shade table from the registry. 
Declaration: br_pixelmap* BrTableRemove (br_pixelmap* pixelmap) 
Arguments: br_pixelmap * pixelmap 
A pointer to a shade table. 
Result: br_pixelmap * 
Returns a pointer to the shade table removed. 
See Also: BrTableAdd () 525 


BrTableRemoveMany () 


Description: | Remove a number of shade tables from the registry. 


Declaration: br_uint_32 
BrTableRemoveMany (br_pixelmap* const* pixelmaps, int n) 
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Arguments: br_pixelmap * const * pixelmaps 
A pointer to an array of pointers to shade tables. 
int n 
Number of shade tables to remove from the registry. 
Result! br_uint_32 
Returns the number of shade tables removed successfully. 
See Also: BrTableAddMany () 5., 


Referencing & Lifetime 


Pixel maps may be freely and multiply referenced. Once added to the registry as a texture map or 
shade table, there are certain restrictions, but they may still be multiply referenced. Maps and tables 
must have been added to the registry if they will be involved in rendering. Texture maps and shade 
tables must be maintained while they are in the registry or being referenced. 


Initialisation 


The structure is initialised by the various construction functions. Pixel maps should not be created or 
initialised by any other means. 


Construction & Destruction 


Apart from platform specific functions, pixel maps should only be constructed by the following 
BRender functions. Destruction should naturally be performed by the corresponding ‘free’ function, 
usually BrPixelmapFree () 5; Note that texture maps and shade tables should be removed from the 
registry before destruction. 


BrPixelmapAllocate () 


Description: Allocate a new pixel map. 


Declaration: br_pixelmap* BrPixelmapAllocate(br_uint_8 type, 
br_uint_16 w, br_uint_16 h, void* pixels, int flags) 


Arguments: br_uint_8 type 
Pixel map type. 
br_uint_16 w 
Width in pixels. 
br_uint_16 h 


Height in pixels. 
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Flags 


BR_PMAF_NORMAL 


BR_PMAF_INVERTED 


Result: 


br_pixelmap 


void * pixels 


A pointer to an existing block of memory. If NULL, the pixel memory is 
allocated automatically using BrResAllocate () 4. 


The calculation obtaining the minimum size required for the block of memory 
is non-obvious. It is row_bytes*h., and row_bytes is not simply w*bits- 
per-pixel/8. To determine row_bytes, it is probably simplest to call this 
function with a dummy, non-NULL pointer (address of an automatic, say), and 
record the value of row_bytes returned in the br_pixelmap,,, (free it 
immediately afterwards). The memory pointed to by pixels is not accessed 
by this function. 

int flags 

Supply either BR_PMAF_NORMAL or BR_PMAF_INVERTED. If the latter, the 
function will automatically set the pixels member of the returned pixel map 


(whether supplied or not) to be at the start of the final row of pixel map memory 
(row_bytes is negative). 


Meaning 

Pixel map ordinate x increases, and y decreases as 
addresses within the memory block ascend. 

Pixel map ordinate x increases, and y increases as 
addresses within the memory block ascend. 





br_pixelmap * 


Returns a pointer to the new pixel map, or NULL if unsuccessful. 


BrPixelmapAllocateSub () 


Description: 


Declaration: 


Arguments: 


Result: 


Remarks: 


Allocate a pixel map as part of an existing pixel map. The new pixel map is 
clipped to the existing pixel map. 


br_pixelmap* BrPixelmapAllocateSub (br_pixelmap* pm, 
br_uint_16 x, br_uint_16 y, br_uint_16 w, br_uint_16 h) 


br_pixelmap * pm 

A pointer to an existing pixel map. 

br_uint_16 x,y 

Co-ordinates of the top left of the new pixel map in the existing pixel map. 
br_uint_16 w,h 

Width and height of the new pixel map. 

br_pixelmap * 

Returns a pointer to the new pixel map, or NULL if unsuccessful. 


The effective origin is set that of the existing pixel map. 
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BrPixelmapMatch () 


Description: | Given a pixel map, allocate either a depth buffer or an off-screen colour buffer 
with the same dimensions. 


Declaration: br_pixelmap* BrPixelmapMatch (const br_pixelmap* src, 
int match_type) 


Arguments: const br_pixelmap * src 
A pointer to the source pixel map. 
int match_type 
The type of matching pixel map required. 


Match Type Match Method 
BR_PMMATCH_OFFSCREEN | Create a pixel map of the same type and dimensions. 


BR_PMMATCH_DEPTH_16 






Create an appropriate 16 bit depth buffer. 


Result: br_pixelmap * 


Returns a pointer to the matching pixel map. 


BrPixelmapClone () 


Description: | Create a pixel map of the same type and dimensions and copy the pixel data. 
Declaration: br_pixelmap* BrPixelmapClone(const br_pixelmap* src) 
Arguments: const br_pixelmap * src 
A pointer to the source pixel map. 
Result: br _pixelmap * 
Returns a pointer to the new pixel map. 


Example: 


br_pixelmap *image, *working_copy; 


image = BrPixelmapLoad(“backdrop.pix”); 


working_copy = BrPixelmapClone (image) ; 


BrPixelmapF ree () 


Description: — Deallocate a pixel map and any associated memory. 


Declaration: void BrPixelmapFree(br_pixelmap* pmap) 
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Arguments: br_pixelmap * pmap 
A pointer to a pixel map. 
Supplementary 


BrPixelmapPixelSize() 


Description: 
Declaration: 


Arguments: 


Result: 


Find the pixel size for a given pixel map. 

br_uint_16 BrPixelmapPixelSize(const br_pixelmap* pm) 
const br_pixelmap * pm 

A pointer to a pixel map. 

br_uint_16 


Returns the size of each pixel, in bits. 


BrPixelmapChannels () 


Description: 
Declaration: 


Arguments: 


Result: 


Find the channels available for a given pixel map. 

br_uint_16 BrPixelmapChannels (const br_pixelmap* pm) 
const br_pixelmap * pm 

A pointer to a pixel map. 

br_uint_16 


Returns a mask giving the available channels, being a combination of the 
following bit value symbols: 


BR_PMCHAN_INDEX 
BR_PMCHAN_RGB 

BR_PMCHAN_DEPTH 
BR_PMCHAN_ALPHA 


BR_PMCHAN_YUV 


BrMapCount () 


Description: 


Declaration: 


Count the number of registered texture maps whose names match a given 


search pattern. The search pattern can include the standard wild cards ‘*’ and 
6p? 


br_uint_32 BrMapCount (const char* pattern) 
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Arguments: 


Result: 


See Also: 


const char * pattern 

Search pattern. 

br_uint_32 

Returns the number of texture maps matching the search pattern. 


BrMapEnum () ,),, BcMapFind () 9; 


BrMapEnum () 


Description: 


Declaration: 


Arguments: 


294 


Result: 


Example: 


Calls a call-back function for every texture map matching a given search 
pattern. The call-back is passed a pointer to each matching item, and its second 
argument is an optional pointer supplied by the user. The search pattern can 
include the standard wild cards ‘*’ and ‘?’. The call-back itself returns a 
br_uint_32,;, value. The enumeration will halt at any stage if the return 
value is non-zero. 


br_uint_32 BrMapEnum(const char* pattern, 
br_map_enum_cbfn* callback, void* arg) 


const char * pattern 

Search pattern. 

br_map_enum_cbfn * callback 

A pointer to a call-back function. 

void * arg 

An optional argument to pass to the call-back function. 
br_uint_32 


Returns the first non-zero call-back return value, or zero if all matching texture 
maps are enumerated. 


br_uint_32 BR_CALLBACK test_callback(br_pixelmap* map, void* arg) 


{ 


br_uint_32 count; 


return(count); 


br_uint_32 enum; 


enum = BrMapEnum(“map”, &test_callback, NULL) ; 
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BrMapF ind () 


Description: | Find a texture map in the registry by name. A call-back function can be setup 
to be called if the search is unsuccessful. The search pattern can include the 
standard wild cards ‘*’ and ‘?’. 


Declaration: br_pixelmap* BrMapFind(const char* pattern) 
Arguments: const char * pattern 
Search pattern. 
Result: br_pixelmap * 


Returns a pointer to the texture map if found, otherwise NULL. Ifa call-back 
exists and is called, the call-back’s return value is returned. 


See Also: BrMapFindHook () 5;, BeMapFindMany () 595 


BrMapF indMany () 
Description: | Find a number of texture maps in the registry by name. The search pattern can 
include the standard wild cards ‘*’ and ‘?’. 


Declaration: br_uint_32 BrMapFindMany (const char* pattern, 
br_pixelmap** pixelmaps, int max) 


Arguments: const char * pattern 
Search pattern. 
br_pixelmap ** pixelmaps 
A pointer to an array of pointers to texture maps. 
int max 
Maximum number of texture maps to find. 
Result! br_uint_32 


Returns the number of texture maps found. The pointer array is filled with 
pointers to the found texture maps. 


See Also: BrMapFind () ».;, BeMapFindHook () 59; 


BrMapFindHook () 


Description: | Functions to set up a call-back. 
Declaration: br_map_find_cbfn* BrMapFindHook (br_map_find_cbfn* hook) 
Arguments: br_map_find_cbfn * hook 


A pointer to a call-back function. 


Copyright © 1996 Argonaut Technologies Limited 2 9 5 


br_pixelmap 


Effects: If BrMapFind () 9; is unsuccessful and a call-back has been set up, the call- 
back is passed the search pattern as its only argument. The call-back should 
then return a pointer to a substitute or default texture map. 


For example, a call-back could be set up to return a default texture map if the 
desired texture map cannot be found in the registry. 


The function BrMapFindFailedLoad () 9, is provided and will probably be 
sufficient in many cases. 

Result: br_map_find_cbfn * 
Returns a pointer to the old call-back function. 


Example: 
br_map BR_CALLBACK * test_callback(char* pattern) 
{ br_map* default_map; 


return (default_map) ; 


{ br_imap* map; 


BrMapF indHook (&test_callback) ; 


map = BrMapFind(“non_existent_map”) ; 


See Also: BrMapFindFailedLoad () 59 


BrMapFindFailedLoad () 


Description: This function is provided as a suitable function to supply to 
BrMapF indHook () 595. 


Declaration: br_pixelmap* BrMapFindFailedLoad(const char* name) 
Arguments: const char * name 
The name supplied to BrMapFind () 45. 


Effects: | Attempts to load the texture map from the filing system using name as the 
filename. Searches in current directory, if not found tries, in order, the 
directories listed in BRENDER_PATH (if defined). If successful, sets this 
name as the identifier of the loaded texture map and adds the texture map to 
the registry. 


Result: br_pixelmap * 
Returns a pointer to the texture map, if found, else NULL. 


Example: 
BrMapF indHook (BrMapFindFailedLoad) ; 


2 9 6 Copyright © 1996 Argonaut Technologies Limited 


br_pixelmap 


BrTableCount () 


Description: 


Declaration: 


Arguments: 


Result: 


See Also: 


Count the number of registered shade tables whose names match a given search 
pattern. The search pattern can include the standard wild cards ‘*’ and ‘?’. 


br_uint_32 BrTableCount (const char* pattern) 
const char * pattern 

Search pattern. 

br_uint_32 

Returns the number of shade tables matching the search pattern. 


BrTableEnum () ,.,, BrTableFind () 59. 


BrTableEnum () 


Description: 


Declaration: 


Arguments: 


Result: 


Example: 


Calls a call-back function for every shade table matching a given search pattern. 
The call-back is passed a pointer to each matching shade table, and its second 
argument is an optional pointer supplied by the user. The search pattern can 
include the standard wild cards ‘*’ and ‘?’. The call-back itself returns a 
br_uint_32,,;, value. The enumeration will halt at any stage if the return 
value is non-zero. 


br_uint_32 BrTableEnum(const char* pattern, 
br_table_enum_cbfn* callback, void* arg) 


const char * pattern 

Search pattern. 

br_table_enum_cbfn * callback 

A pointer to a call-back function. 

void * arg 

An optional argument to pass to the call-back function. 
br_uint_32 


Returns the first non-zero call-back return value, or zero if all matching shade 
tables are enumerated. 


br_uint_32 BR_CALLBACK test_callback (br_pixelmap* table, void* arg) 





br_uint_32 count; 


return(count); 


br_uint_32 enum; 


enum = BrTableEnum(“Table”, &test_callback, NULL) ; 
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BrTableFind () 


Description: — Finda shade table in the registry by name. A call-back function can be setup to 
be called if the search is unsuccessful. The search pattern can include the 
standard wild cards ‘*’ and ‘?’. 


Declaration: br_pixelmap* BrTableFind(const char* pattern) 
Arguments: const char * pattern 
Search pattern. 
Result: br _pixelmap * 


Returns a pointer to the shade table if found, otherwise NULL. Ifa call-back 
exists and is called, the call-back’s return value is returned. 


See Also: BrTableFindHook () 9, BrTableFindMany () 5. 


BrTableFindMany () 


Description: | Find a number of shade tables in the registry by name. The search pattern can 
include the standard wild cards ‘*’ and ‘?’. 


Declaration: br_uint_32 BrTableFindMany (const char* pattern, 
br_pixelmap** pixelmaps, int max) 


Arguments: const char * pattern 
Search pattern. 
br_pixelmap ** pixelmaps 
A pointer to an array of pointers to shade tables. 
int max 
Maximum number of shade tables to find. 
Result! br_uint_32 


Returns the number of shade tables found. The pointer array is filled with 
pointers to the found shade tables. 


See Also: BrTableFind () 5., BrTableFindHook () 55 
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BrTableFindHook () 


Description: 


Declaration: 


Arguments: 


Result: 


Example: 


Functions to set up a call-back. If BrTableFind () 4. is unsuccessful and a call- 
back has been set up, the call-back it is passed the search pattern as its only 
argument. The call-back should then return a pointer to a substitute or default 
shade table. 


For example, a call-back could be set up to return a default shade table if the 
desired shade table cannot be found in the registry. 


The function BrTableFindFailedLoad () 9) is provided and will probably 
be sufficient in many cases. 


br_table_find_cbfn* 
BrTableFindHook (br_table_find_cbfn* hook) 


br_table_find_cbfn * hook 
A pointer to a call-back function. 
br_table_find_cbfn * 


Returns a pointer to the old call-back function. 


br_table BR_CALLBACK * test_callback(char* pattern) 
{ britable* default_table; 


return(default_table); 


{ br_table* table; 


BrTableFindHook (&test_callback) ; 


} 
See Also: 


table = BrTableFind(“non_existent_table”); 


BrTableFindFailedLoad () 5, 


BrTableFindFailedLoad () 


Description: 


Declaration: 


Arguments: 


This function is provided as a suitable function to supply to 
BrTableFindHook () 59. 


br_pixelmap* BrTableFindFailedLoad(const char* name) 
const char * name 


The name supplied to BrTableFind () 5s. 
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Effects: | Attempts to load the shade table from the filing system using name as the 
filename. Searches in current directory, if not found tries, in order, the 
directories listed in BRENDER_PATH (if defined). If successful, sets this 
name as the identifier of the loaded shade table and adds the shade table to the 
registry. 

Result! br_pixelmap * 

Returns a pointer to the shade table, if found, else NULL. 


Example: 
BrTableFindHook (BrTableFindFailedLoad) ; 
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Import & Export 


BrPixelmapFileCount () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


Locate a given file and count the number of pixel maps in it. 

br_uint_32 BrPixelmapFileCount (const char* filename, 
br_uint_16* num) 

const char * filename 

Name of the file containing the pixel maps to count. 

br_uint_16 * num 

Pointer to the variable in which to store the number of pixel maps counted in 


the file. If NULL, the file will still be located and appropriate success returned, 
but no count will be made. 


Searches for filename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). Ifa file is found, will count the number of pixel maps stored in it. 


br_uint_32 


Returns zero if the file was found (even if it is not a pixel map file), non-zero 
otherwise. 


BrPixelmapLoad () 


Description: 
Declaration: 


Arguments: 


Effects: 


Result: 


See Also: 


Load a pixel map. Note that they are not added to the registry. 
br_pixelmap* BrPixelmapLoad(const char* filename) 
const char * filename 

Name of the file containing the pixel map to load. 


Searches for f i lename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). 


br_pixelmap * 
Returns a pointer to the loaded pixel map, or NULL if unsuccessful. 


BrPixelmapLoadMany () ,,, BrePixelmapSave () 3,,, BeMapAdd () 53, 
BrTableAdd () 53. 


BrPixelmapLoadMany () 


Description: 
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Load a number of pixel maps. Note that they are not added to the registry. 
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Declaration: 


Arguments: 


Effects: 


Result: 


See Also: 


br_uint_32 BrPixelmapLoadMany (const char* filename, 
br_pixelmap** pixelmaps, br_uint_16 num) 


const char * filename 

Name of the file containing the pixel maps to load. 
br_pixelmap ** pixelmaps 

A non-NULL pointer to an array of pointers to pixel maps. 
br_uint_16 num 

Maximum number of pixel maps to load. 


Searches for filename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). 


br_uint_32 


Returns the number of pixel maps loaded successfully. The pointer array is 
filled with pointers to the loaded pixel maps. 


See BrPixelmapFileCount () ,,, to determine the number of pixel maps ina 
file. 


BrFmtBMPLoad () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


Load a pixel map in the BMP format. 


br_pixelmap* BrFmtBMPLoad(const char* name, 
br_uint_32 flags) 


const char * name 
Name of the file containing the pixel map. 
br_uint_32 flags 


Either BR_PMT_RGBX_888 or BR_PMT_RGBA_8888, when the source pixel map 
uses 32 bits per pixel. Zero otherwise. 


Searches for filename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). 


br_pixelmap * 


Returns a pointer to the loaded pixel map. 


BrFmtGIFLoad () 


Description: 


Declaration: 


302 


Load a pixel map in the GIF format. 


br_pixelmap* BrFmtGIFLoad(const char* name, 
br_uint_32 flags) 
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Arguments: 


Effects: 


Result: 


br_pixelmap 


const char * name 

Name of the file containing the pixel map. 

br_uint_32 flags 

Either BR_PMT_RGBX_888 or BR_PMT_RGBA_8888, when the source pixel map 
uses 32 bits per pixel. Zero otherwise. 


Searches for filename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). 


br_pixelmap * 


Returns a pointer to the loaded pixel map. 


BrFmt IFFLoad () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


Load a pixel map in the IFF format. 


br_pixelmap* BrFmtIFFLoad(const char* name, 
br_uint_32 flags) 


const char * name 
Name of the file containing the pixel map. 
br_uint_32 flags 


Either BR_PMT_RGBX_888 or BR_PMT_RGBA_8888, when the source pixel map 
uses 32 bits per pixel. Zero otherwise. 


Searches for filename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). 


br_pixelmap * 


Returns a pointer to the loaded pixel map. 


BrFmt TGALoad () 


Description: 


Declaration: 


Arguments: 


Load a pixel map in the TGA format. 


br_pixelmap* BrFmtTGALoad(const char* name, 
br_uint_32 flags) 


const char * name 
Name of the file containing the pixel map. 
br_uint_32 flags 


Either BR_PMT_RGBX_888 or BR_PMT_RGBA_8888, when the source pixel map 
uses 32 bits per pixel. Zero otherwise. 
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Effects: | Searches for filename, if no path specified with file looks in current directory, 
if not found tries, in order, the directories listed in BRENDER_PATH (if 
defined). 


Result: br_pixelmap * 


Returns a pointer to the loaded pixel map. 


BrPixelmapSave () 


Description: | Save a pixel map to a file. 


Declaration: br_uint_32 BrPixelmapSave (const char* filename, 
const br_pixelmap* pixelmap) 


Arguments: const char * filename 
Name of the file to save the pixel map to. 
const br_pixelmap * pixelmap 
A pointer to a pixel map. 
Effects: | Writes the pixel map toa file’. 
Result! br_uint_32 


Returns NULL if the pixel map could not be saved. 


BrPixelmapSaveMany () 


Description: | Save a number of pixel maps to a file. 


Declaration: br_uint_32 BrPixelmapSaveMany (const char* filename, 
const br_pixelmap* const* pixelmaps, br_uint_16 num) 


Arguments: const char * filename 
Name of the file to save the pixel maps to. 
const br_pixelmap * const * pixelmaps 


A pointer to an array of pointers to pixel maps. If NULL, all registered texture 
maps and shade tables are saved (irrespective of num). 


br_uint_16 num 

Number of pixel maps to save. 
Effects: | Writes the pixel maps to a file’. 
Result! br _uint_32 


Returns the number of pixel maps saved successfully. 





* Any existing file of the same name is overwritten. 
+ Any existing file of the same name is overwritten. 


3 04 Copyright © 1996 Argonaut Technologies Limited 


br_pixelmap 


Copyright © 1996 Argonaut Technologies Limited 3 O 5 


br_pool 


br_pool 


The Structure 


This structure holds details of amemory block pool (an optimised memory allocation scheme on a per 
data structure basis). This is ideal for cases where a particular data structure has intensive dynamic 
storage, e.g. matrices. 


Note that currently, there is no automatic contraction of Pools, nor are there functions to achieve this 
(with the current implementation it would have a relatively high processing overhead). Therefore, it 
may be wise to destroy Pools when possible, if they have irregular or sporadic use, or memory is at a 
premium. 


The typedef 


(See pool.h for precise declaration and ordering) 


Primary 

br_pool_block * free Linked list of unused blocks 
br_uint_32 block_size Size of each item 

br_uint_32 chunk_size Number of blocks to increase pool by 
int mem_type Memory class of blocks 

Related Functions 


Memory Management 


BrAllocatorSet () 13. 


Members 
Primary 


br_pool_block * free 


This is a pointer to the next available block of memory (of size block_size). When freed, blocks 
are castas br_pool_block,,, and inserted at the head of the list to keep track of them. An allocation 
simply removes the item at the head from the list. It may then be initialised as required. 


br_uint_32 block_size 


This is the size of each item, or memory block. Its value must be greater than or equal to 
sizeof (br_pool_block), if not, memory corruption will ensue. This is typically 4 bytes, but 
given that pools are intended for larger structures, this is not a significant restriction. See 
BrPoolAllocate () 30. 
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br_uint_32 chunk_size 


When all the blocks ina pool are allocated (or the pool is empty), the value of this member determines 
the number of blocks that will be added to the pool to enable further block allocations. 


uint mem_type 


This is the memory class from which the blocks should be allocated. Any number of pools may exist 
for a given memory class. 


Operations 


BrPoolBlockAllocate () 


Description: 
Declaration: 


Arguments: 


Result: 


Allocate a block from a pool. If the pool is full, it will expand as necessary. 
void* BrPoolBlockAllocate (br_pool* pool) 

br_pool * pool 

A pointer to the relevant pool. 

void * 


Returns a pointer to the allocated block, or NULL if unsuccessful. 


BrPoolBlockF ree () 


Description: 
Declaration: 


Arguments: 


Deallocate a block from a pool. 

void BrPoolBlockFree(br_pool* pool, void* b) 
br_pool * pool 

A pointer to the relevant pool. 

void * b 


A pointer to the block to deallocate. 


BrPoolEmpty () 


Description: 
Declaration: 


Arguments: 


Mark all blocks in a pool as unused. 
void BrPoolEmpty (br_pool* pool) 
br_pool * pool 


A pointer to the pool to be emptied. 
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Copy/Assign 


Do not copy. 


Access & Maintenance 


No members should be modified. The structure will be maintained until the pool is freed using 
BrPoolFree () 39). No additional maintenance required. 


Referencing & Lifetime 


Do not reference a copy. Ensure that references to a pool descriptor do not outlast the pool. 


Initialisation 


Initialisation is performed by BrPoolAllocate () xs. 


Effectively this sets free to NULL, block_size to the specified value (aligned appropriately), 
chunk_size tothe specified value, and mem_type to the specified value. 


Construction & Destruction 


Memory pool structures should be constructed by BrPoolAllocate () 3g, as this will allocate the 
pool descriptors from the pool resource class. Some Pool functions depend on this. 


BrPoolAllocate () 


Description: 


Declaration: 


Arguments: 


308 


Create a new block pool. 

br_pool* BrPoolAllocate (int block_size, int chunk_size, 
br_uint_8 mem_type) 

int block_size 

The size of each block, in bytes. Minimum value is 1, though note that this size 


will be rounded up to the next multiple of a suitable alignment factor, typically 
8 (BR_POOL_ALIGN+1). Pools are not intended for simple data structures. 


int chunk_size 


The number of blocks to allocate each time the pool becomes full. The value 
should be between 1 and say, 10% of the maximum number of blocks allocated 
at any one time. Naturally, there is a compromise between saving processing 
overhead for each memory allocation (only when the pool grows), and saving 
memory overhead in terms of average unused blocks. 

br_uint_8 mem_type 


Memory type. More than one pool may be created fora particular memory class. 
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Result: br_pool * 
Returns a pointer to the new pool, or NULL if it could not be created. 


BrPoolFree () 
Description: — Deallocate an entire pool, thereby losing any blocks it may contain. 
Declaration: void BrPoolFree(br_pool* pool) 


Arguments: br_pool * pool 
A pointer to the pool to be deallocated. 


Supplementary 
Given that Pools are registered in the “POOL” resource class, the resource class supplementary 


functions are available. 


Copyright © 1996 Argonaut Technologies Limited 3 O9 


br_pool_block 


br_ pool block 


The Structure 
This structure is simply used as a means of ‘spiking’ freed pool blocks until they can be reused. 
(See pool.h for precise declaration and ordering) 


The typedef 


Primary 
br_pool_block * next Pointer to next free block 


Related Functions 


Memory Management 


BrPoolBlockAllocate () ,,,, BrPoolBlockFree () 3,;. 


Members 
Primary 
br_pool_block * next 


A pointer to the next free pool block. This is really an area of memory with size as specified in the 
pool descriptor (br_pool,,,). 


Copy/Assign 


Don’t copy or reference. 


Access & Maintenance 


Should not be accessed by the applications programmer. 


Referencing & Lifetime 


Should not be referenced by the applications programmer. 
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Initialisation 


When a pool block is spiked onto the free linked list, it is cast to this structure, the next member is 
set to point to free, and free is then set to point to this. 


Construction & Destruction 


The structure is only used for casting purposes. 
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The Structure 


The primitive is an item of rendering data produced in the second phase of rendering. It is typically 
a lit face of a model, transformed into screen co-ordinates. It contains sufficient information (some 
private) to be depth sorted and rendered to the destination pixel map. The application programmer 
will only be handling primitives as far as is necessary to determine whether the primitive should 
appear and in what order it should be rendered. Primitives are only generated by BRender. 


The typedef 


(See order.h fora precise declaration) 


Properties 

br_uint_16 type Primitive type 

br_material * material Material from which primitive was generated 
Organisation 

br_primitive * next Next primitive (when in bucket) 

Related Functions 


For details of how to specify that a primitive call-back function should be called during rendering see 
BrZsPrimitiveCallbackSet () 3. To determine into which bucket a primitive would be inserted 
see BrZsPrimitiveBucketSelect () ;,.. To insert a primitive into an order table see 
BrZsOrderTablePrimitivelInsert () 557. 


Related Structures 


See br_order_table,,, for the container into which primitives are inserted. See 
br_primitive_cbfn,,,; for details of how to customise primitive insertion into order tables. 


Members 


Properties 


br_uint_16 type 


There are currently three types of primitive: point, line and triangle. This member indicates the type 
of this primitive. It should not be modified. The following table lists the symbols defining the value 
of each type. 
Primitive Type Description 


BR_PRIMITIVE_POINT The primitive is a point defined by a single vertex 
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BR_PRIMITIVE_LINE The primitive is a line defined by two vertices 


BR_PRIMITIVE_TRIANGLE |The primitive is a triangle defined by three vertices 





br_material * material 


The material assigned to the face of the model from which the primitive was generated (explicitly or 
by inheritance). 


Organisation 


br_primitive * next 


Each bucket within an order table is a linked list of primitives. The primitive contains the links in 
the form of this pointer. When a primitive is inserted into a bucket, it is inserted at the head (the first 
bucket in the list). Upon rendering the buckets are rendered from the head onwards. This member 
should not be modified. 


Copy/Assign 


Do not copy primitives. 


Access & Maintenance 


Primitives are only generated by BRender, and are primarily for internal use. The applications 
programmer is not expected to traverse or maintain primitives. Some members may be usefully read, 
but modification is not encouraged for members other than material. 


Referencing & Lifetime 


Primitives are allocated from the primitive heap as supplied to BrZsBegin () 5s. They are valid until 
the next call of BrZsSceneRenderBegin () ,, when the primitive heap will be overwritten with new 
primitives - unless, of course a different one is set up. 


Construction & Destruction 


Primitives can only be constructed through the rendering process. They are never destroyed, but are 
overwritten. 
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br primitive_cbfn 


‘The Call-Back Function 


This type defines a call-back function, which can be specified by using the function 
BrZsPrimitiveCallbackSet () ,9. It is called for each primitive generated from a model actor in the 
actor hierarchies supplied to BrZsSceneRender (),, and BrZsSceneRenderAdd ();, (it may also 
be called by BrZsModelRender (),;,). It enables an application to perform customised insertion of 
primitives into order tables, or to perform computations that require information only obtainable just 
after a primitive has been generated by the rendering engine. 


The typedef 


(See zsproto.h fora precise declaration) 

void br_primitive_cbfn(br_primitive*, br_actor*, const br_model*, const br_material*, 
br_order_table*, const br_scalar*) 
Primitive call-back 


Related Functions 


For details of how to specify that a primitive call-back function should be called during rendering see 
BrZsPrimitiveCallbackSet () 39. 


Functions dedicated for use within primitive call-backs: BrZsOrderTablePrimitiveInsert () 5.7, 
BrZsPrimitiveBucketSelect () 3,., BrOnScreenCheck () ,;,, BrOriginToScreenxY () 5;5, 
BrPointToScreenxyY (),,;, BrePointToScreenXYMany () 5;,, BrOriginToScreenXYZO () 556, 
BrPointToScreenxXYZO() ,;,, BrPointToScreenXYZOMany () 55. 


Related Structures 


See br_primitive,,, for details of the primitive data structure. See br_model_custom_cbfn,,, 
for a substitute custom model rendering call-back. See br_order_table.,,, for details of inserting 
primitives into order tables. 


Specification 


CBFnPrimitive () 


Description: — An application defined call-back function that is called at some point during 
rendering — at precisely what point is undefined, and whether its children have 
been processed is also undefined. The pass through equivalent for this call-back is 
described in the example. The function may call any non-rendering functions 
available to a model’s custom call-back function — see 
br_model_custom_cbfn,,,. 
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Declaration: void BR_CALLBACK CBFnPrimitive (br_primitive* primitive, 
br_actor* actor, const br_model* model, const 
br_material* material, br_order_table* order_table, const 
br_scalar* z) 


Arguments: br_primitive * primitive 
Primitive to be inserted in order_table. 
br_actor * actor 


Pointer to model actor referencing the model from which the primitive was 
generated. 


const br_model * model 

Pointer to the model from which the primitive was generated. 

const br_material * material 

Pointer to actor’s material if defined, or default material otherwise. 
br_order_table * order_table 

Order table into which the primitive was about to be inserted. 

const br_scalar * z 

Non-NULL pointer to one or more depth values of the primitive’s vertices 
([-hither_z, -yon_z] in camera co-ordinate space (linearly) mapped to 


[-hither_z,+yon_z]). The number of values pointer to can be determined from 
the type member of primitive. 


Preconditions: | BRender has completed initialisation. Rendering is in progress (by the Z-Sort 
renderer). The rendering engine has generated a primitive that faces the viewer. 


Effects: | Behaviour is up to the application. Any of the operations described for 
br_model_custom_cbfn,,, can be used apart from 
Br[Zb|Zs]ModelRender () 553,54. 


Remarks: — Any other BRender functions may be called from within this call-back with the 
following restrictions: 


e Don’t call any rendering functions, e.g. BreZsSceneRenderAdd () ;,. 
e Don’t modify any light, clip-plane or camera actors. 
e Do not access output buffer until rendering has completed. 
e Don’t change the environment actor. 
e For best performance, avoid adding, updating or removing registry items — try 
to do these things before rendering. 
¢ Do not modify the actor hierarchy. 
Example: The following code demonstrates a primitive call-back function that performs the 


equivalent of BRender’s normal primitive insertion, and so can be used for 
collection of statistics, say. 


void BR_CALLBACK CBFnPrimitive(br_primitive* primitive, br_actor* 
actor, const br_model* model, const br_material* material, 
br_order_table* order_table, const br_scalar* 2) 
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BrZsOrderTablePrimitivelInsert 

( order_table 

, primitive 

, BrZsPrimitiveBucketSelect 

f° 2 

primitive-—>type 
order_table->min_z 
order_table->max_z 
order_table->size 


order_table->type 


/* Collect statistics here */ 


See Also: br_primitive,,,,br_model_custom_cbfn,,;,, br_pick2d_cbfn,,,, 
br_pick3d_cbfn,,,, BrZsOrderTablePrimitiveInsert () 5,,, 
BrZsPrimitiveBucketSelect () 3). 


Operations 


The following functions are provided solely for appropriate use within CBFnModelCustom (),,,, 
CBFnRenderBounds (),,, and CBFnPrimitive () ;,, functions (see 
br_model_custom_cbfn,,,). 


BrZsOrderTablePrimitivelInsert () 5,7 
BrZsPrimitiveBucketSelect()3;¢ 
BrOnScreenCheck () 55, 
BrOriginToScreenxY () 5;; 
BrPointToScreenxyY () 5; 
BrPointToScreenxXYMany () 556 
BrOriginToScreenxXYZO () 556 
BrPointToScreenxXYZO () 557 
BrPointToScreenxXYZOMany () 5;. 


BrZsPrimitiveBucketSelect () 


Description: | Determine into which bucket a primitive would be placed given a particular sorting 
method. 
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Declaration: 


Arguments: 


Result: 


Remarks: 


318 


br_uint_16 BrZsPrimitiveBucketSelect (const br_scalar* z, 
br_uint_16 pr_type, br_scalar min_z, br_scalar max_z, 
br_uint_16 ot_size, br_uint_16 ot_type) 


const br_scalar * z 


Anon-NULL pointer to the z values corresponding to each vertex. This should point 
to as many values as are indicated by the primitive type pr_type. 

br_int_16 pr_type 

The primitive type (see br_primitive,,,). 

br_scalar min_z, max_z 

Depth range of buckets (use BrZsScreenZToDepth () ;; if wishing to work with 
screen ordinates). 

br_uint_16 ot_size 

Number of buckets (see br_order_table,,,). 

br_uint_16 ot_type 

How the bucket should be determined (see br_order_table,,,). 
br_uint_16 

The index of the bucket as would be passed to 
BrZsOrderTablePrimitivelInsert () 5... 


Although the calculation performed by this function is trivial, it is provided to allow 
applications to ensure that the same bucket selection occurs in primitive call-back 
functions as would occur otherwise. 
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The Structure 


The quaternion is an extension of the complex number, with the addition of two further imaginary 
components. BRender restricts itself to using unit quaternions, which have the useful property of 
being able to easily represent a 3D transform consisting of a rotation about an arbitrary vector. 


The x, y and z components of the quaternion hold the elements of this vector scaled to a length equal 
to the sine of half the angle of rotation. The w component holds the cosine of half the angle. The 
magnitude of a unit quaternion is of course 1 (w?+x?+y?+z7=1). 


The quaternion is written thus: 


w+xit+yj+zk 


NB Do not confuse the quaternion with 3D vectors or homogenous co-ordinates, i.e. br_quat,,, and 
br_vector4,,, have no relationship. 


The typedef 


(See qguat.h for precise declaration and ordering) 

br_scalar w Real component 

br_scalar x “’ component (vector, x axis component) 
br_scalar y 7 component (vector, y axis component) 
zZ 


br_scalar ‘k’ component (vector, 3 axis component) 


Related Functions 


Maths 


See BrEulerToQuat () ,,,, BeMatrix34ToQuat (),,.,, BeMatrix4ToQuat (),,.. 


Related Structures 


See br_transform,,. 


Members 
br_scalar w 


Real component of quaternion. Represents the cosine of half the rotation about the (i,j,k) vector 
component of the quaternion. 
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br_scalar x 


First imaginary component of quaternion. Represents the x axis component of the vector about which 


the rotation occurs. 


be-scalar 4 


Second imaginary component of quaternion. Represents the y axis component of the vector about 
which the rotation occurs. 


br scalar z 


Third imaginary component of quaternion. Represents the z axis component of the vector about 
which the rotation occurs. 


Arithmetic 


BrQuatMul () 


Description: 


Declaration: 


Arguments: 


Effects: 


Result: 


320 


Multiply two quaternions. 


br_quat* BrQuatMul (br_quat* q, const br_quat* 1, 
const br_quat* r) 


br_quat * q 

A pointer to the destination quaternion (may be same as either source). 
const br_quat * 1 

A pointer to the left hand source quaternion. 

const br_quat * r 

A pointer to the right hand source quaternion. 


The resultant quaternion is computed as follows: 


(w,+xit+ yj t+ zk)(w,++,i+ y,j+z,kK) = 
WW, — X}X~ — VV — Shr 
+(w)X, + XW, + V2, 2) 

+(wiy, + yw, + ZX, -XZ,)J 


+(w/Z, + ZW, + xy, — y/X,)k 


br_quat * 


The destination quaternion pointer is returned as supplied for convenience. 
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Remarks: | Quaternion multiplication has the effect of concatenating the individual 
transformations that each represents. It is not commutative. 


BrQuatInvert () 


Description: | Obtain the inverse of a unit quaternion. This is effectively the rotation reversed 
(about the same vector component). 


Declaration: br_quat* BrQuatInvert (br_quat* q, const br_quat* qq) 
Arguments: br_quat * q 
A pointer to the destination quaternion (can be same as source). 
const br_quat * qq 
A pointer to the source quaternion. 


Effects: "The resultant quaternion is computed as follows: 
. . -l . ° 
(w+xityj+zk) =w-xi-yj-zk 
Result: br_quat * 


The destination quaternion pointer is returned as supplied for convenience. 


BrQuatSlerp () 


Description: | The ‘Slerp’ operation (spherical, linear interpolation) interpolates linearly between 
two quaternions along the most direct path between the two orientations. 


Declaration: br_quat* BrQuatSlerp(br_quat* q, const br_quat* 1, 
const br_quat* r, br_scalar t, br_int_16 spins) 


Arguments: br_quat * q 
A pointer to the destination quaternion (can be same as either source). 
const br_quat * 1 
A pointer to the starting quaternion (equivalent to result with t=0). 
const br_quat * 1 
A pointer to the finishing quaternion (equivalent to result with t=1). 
br_scalar t 
Interpolation parameter in the range [0,1]. 
br_int_16 
Number of extra spins in the interpolated path. 


A special value of zero causes interpolation along the shortest path. 


A special value of -1 causes interpolation along the longest path. 


Effects: 
Computes the quaternion between 1 andr corresponding to position t along the 
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interpolated path between them. 
Result: br_quat * 


The destination quaternion pointer is returned as supplied for convenience. 


Conversion 


From Eulers and Matrices 


See BrEulerToQuat () ,,,, BeMatrix34ToQuat () »),, BeMatrix4ToQuat () ,9;. 


To Eulers and Matrices 


See BrQuatToEuler () ,,, BrQuat ToMat rix34 () ,,;, and BrQuat ToMatrix4 (),, as described 
below. 


Also see BrTransformToTransform () 353. 


BrQuatToEuler () 


Description: | Convert a unit quaternion to an Euler angle set, that would have the same 
transformational effect. 


Declaration: br_euler* BrQuatToEuler (br_euler* euler, const br_quat* q) 
Arguments: br_euler * euler 
A pointer to the destination Euler angle set to receive the conversion. 
const br_quat * q 
A pointer to the source unit quaternion. 
Result: br euler * 


Returns euler for convenience. 


BrQuat ToMatrix34 () 


Description: | Convert a unit quaternion to a 3D affine matrix, that would have the same 
transformational effect. 


Declaration: br_matrix34* BrQuatToMatrix34 (br_matrix34* mat, 
const br_quat* q) 
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Arguments: br_matrix34 * mat 
A pointer to the destination matrix to receive the conversion. 
const br_quat * q 
A pointer to the source unit quaternion. 
Result: br _matrix34 * 


Returns mat for convenience. 


Remarks: The resulting matrix at mat is equivalent to the following: 


1-4(y +2) 4(xy+wz) 4(xz-wy) 0 


wtxityjtcks| 4069-2) 1-4(x° +z) 4(yz+wx) 0 


4(xz+ wy) 4(yz- wx) 1-4(x"+y’) 0 
0 0 0 1 


BrQuatToMatrix4 () 


Description: | Convert a unit quaternion to a 3D affine matrix, that would have the same 
transformational effect. 


Declaration: br_matrix4* BrQuatToMatrix4 (br_matrix4* mat, 
const br_quat* q) 


Arguments: br_matrix4 * mat 
A pointer to the destination matrix to receive the conversion. 
const br_quat * q 
A pointer to the source unit quaternion. 


Result: br _matrix4 * 


Returns mat for convenience. 
See Also: BrQuatToMatrix34 () 5). 


Copy/Assign 


Use structure assignment to copy quaternions. 


Access & Maintenance 


Members may be freely accessed. Maintenance is only required for unit quaternions that have been 
modified. 
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BrQuatNormalise () 


Description: | Normalise a quaternion. 
Declaration: br_quat* BrQuatNormalise(br_quat* q, const br_quat* qq) 
Arguments: br_quat * q 
A pointer to the destination quaternion (may be same as source). 
const br_quat * qq 
A pointer to the source quaternion. 
Effects: ‘The destination is each element of the source divided by its magnitude. 


Remarks: | BRender assumes that only unit quaternions are used, and due to this assumption 
being embodied in certain calculations, if non-unit quaternions are used it is likely 
that unwanted side effects such as scaling will be introduced. This function ensures 
that the quaternion is a unit one, and is intended to be applied to unit quaternions 
that have resulted from a large number of intermediate calculations and may have 
drifted (due to precision limitations) from unit magnitude. 


Initialisation 


The following macro may be used as a static initialiser. Note the order in which the components are 
specified. 


BR_QUAT (x, y,Z,w) 


Macro expands to 
{BR_SCALAR (x) , BR_SCALAR (y) , BR_SCALAR(z) , BR_SCALAR (w) }. 


All other initialisation should be member-wise or by using structure assignment. 
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br renderbounds cbfn 


‘The Call-Back Function 


This type defines a call-back function, which can be specified by using the function 
Br[Zb|Zs]RenderBoundsCallbackSet () 39)39. It is called for each rendered model actor in the actor 
hierarchies supplied to Br[Zb|Zs]SceneRender () ,,,,, and Br[ZblZs]SceneRenderAdd () 5.3, (it 
may also be called by Br[ZblZs]ModelRender () ,;3,;,). It enables an application to perform extra 
rendering for particular actors, or to perform computations that require information only obtainable 
just after a model actor has been processed by the rendering engine. 


The typedef 


(See zbproto.h fora precise declaration) 

void br_renderbounds_cbfn(br_actor*, const br_model*, const br_material*, void*, 
br_uint_8, const br_matrix4*, const br_int_32 [4]) Render 
bounds call-back 


Related Functions 


For details of how to specify that a render bounds call-back function should be called during 
rendering see Br[Zb|Zs]RenderBoundsCallbackSet () sg). 


Functions dedicated for use within rendering call-backs: Br[ZblZs ]ModelRender () 55354, 
BrOnScreenCheck () 5;,, BrOriginToScreenxY (),,;;, BcPoint ToScreenxY () 5;;, 
BrPointToScreenxXYMany () »;,, BrOriginToScreenXYZO () »,,, BrPointToScreenXYZO () 57, 
BrPointToScreenXYZOMany () 553. 


Related Structures 


See br_model_custom_cbfn,,, for a substitute model rendering call-back. 


Specification 


CBFnRenderBounds () 


Description: | An application defined call-back function that is called for each rendered model, at 
some point during rendering — at precisely what point is undefined, except that its 
parents have been processed (though not necessarily rendered). The pass through 
equivalent for this call-back is to do nothing. The function may call any non- 
rendering functions available to a model’s custom call-back function — see 
br_model_custom_cbfn,,,. 
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Declaration: 


Arguments: 


Preconditions: 


Effects: 


Remarks: 


326 


void BR_CALLBACK CBFnRenderBounds (br_actor* actor, 
const br_model* model, const br_material* material, 
void* render_data, br_uint_8 style, 

const br_matrix4* model_to_screen, 

const br_int_32 bounds [4]) 


br_actor * actor 

Pointer to model actor referencing the model. 

const br_model * model 

Pointer to a model that has affected the rendering. 

const br_material * material 

Pointer to actor’s material if defined, or default material otherwise. 

void * render data 

If the function is called during a rendering performed by the Z-Sort renderer this 


will point to the order table into which the model actor’s primitives have been 
inserted. 


br_uint_8 style 


Actor’s rendering style, or default. BRender will not supply 
BR_RSTYLE_BOUNDING_- or BR_RSTYLE_NONE. 








const br_matrix4 * model_to_screen 
A pointer to a matrix giving the model to screen transformation. 
const br_int_32 bounds [4] 


An array containing minimum and maximum screen ordinates of pixels that would 
be modified in the process of rendering the model. Use the following symbols to 
obtain each ordinate: 


Ordinate Obtained 


Left-most column in which pixels are modified 


Index Symbol 
BR_BOUNDS_MIN_X 
BR_BOUNDS_MAX_X | Right-most column in which pixels are modified 


BR_BOUNDS_MIN_Y | Top-most row in which pixels are modified 





BR_BOUNDS_MAX_Y | Bottom-most row in which pixels are modified 


BRender has completed initialisation. Rendering is in progress. The rendering 
engine has determined that the model will affect pixels in the output buffers. 


Behaviour is up to the application. Any of the operations described for 
br_model_custom_cbfn,,, can be used except 
Br[Zb|Zs]ModelRender () 553,54. 


This function may also be called as a result of calling 
Br[ZblZs]ModelRender () 55354, so if you are highlighting a model’s edges say, be 
careful that you don’t accidentally over recurse. 
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Example: 


br_renderbounds_cbfn 


Any other BRender functions may be called from within this call-back with the 
following restrictions: 


Don’t call any rendering functions. 

Don’t modify any light, clip-plane or camera actors. 

Do not access output buffers until rendering has completed. 
Don’t change the environment actor. 


For best performance, avoid adding, updating or removing registry items — try 
to do these things before rendering. 


Do not modify the actor hierarchy. 


Possible uses include: 


Dirty Rectangle Tracking (tracking modified areas of the screen pixel map). 
Monitoring the set of model actors currently on screen 
Labelling, selection, highlighting 


Collision detection (not necessarily indicating the best method) 


Note that a suitable call to clear the area of a pixel map for the purpose of clearing 
dirty rectangles only, is as follows: 


BrPixelmapDirtyRectangleFill 


( 


See Also: 


Operations 


pixel_map 


bounds [ 

bounds [ 

bounds [BR_BOUNDS_MAX_X 
[ 


bounds 


0 


BR_BOUNDS_MIN_X] 
BR_BOUNDS_MIN_Y] 
]-bounds [BR_BOUNDS_MIN_X]+1L 
]-bounds [BR_BOUNDS_MIN_Y]+1L 


BR_BOUNDS_MAX_Y 


br_model_custom_cbfn,,,, br_primitive_cbfn,,., 
br_pick2d_cbfn,,,, br_pick3d_cbfn,,,. 


The following functions are provided solely for use within CBFnMode1Custom (),.,, 
CBFnPrimitive(),,, and CBFnRenderBounds (),,, functions (see 
br_model_custom_cbfn,,,). 


BrOnScreenCheck () ,<, 
BrOriginToScreenxY () 5;; 
BrPointToScreenxyY () 55; 
BrPointToScreenXYMany () 556 
BrOriginToScreenxXYZO () 55. 
BrPointToScreenxXYZO () 557 
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br_renderbounds_chfn 


BrPointToScreenXYZOMany () 55. 
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br_resclass_enum_chfn 


br resclass enum _cbfn 


‘The Call-Back Function 


This type defines a function, supplied to BrResClassEnum () 3,9, and to be called by it for a selection 


of resource classes. 


(See fwproto.h fora precise declaration) 


The typedef 


br_uint_32 


br_resclass_enum_cbfn(br_resource_class *,void *) Enuwmerator 


Specification 


CBFnResClassEnum () 


Description: 


Declaration: 


Arguments: 


Preconditions: 
Effects: 


Result: 


See Also: 


An application defined call-back function accepting a resource class and an 
application supplied argument (as supplied to BrResClassEnum () 349). 


br_uint_32 BR_CALLBACK 
CBFnResClassEnum(br_resource_class* item, void* arg) 


br_resource_class * item 

One of the resource classes selected by BrResClassEnum () 349. 
void * arg 

The argument supplied to BrResClassEnum () 34. 

BRender has completed initialisation. 


Application defined. Avoid adding or removing resource classes within this 
function. 


br_uint_32 
Any non-zero value will terminate the enumeration and be returned by 
BrResClassEnum () ,,). Return zero to continue the enumeration. 


BrResClassEnum () 3,), BsResChildEnum () 5). 
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br_resclass_1 








fFind_chfn 


br resclass find cbfn 


‘The Call-Back Function 


This type defines a function, registered with BrResClassFindHook () 3, to be called when 
BrResClassFind () ,,., or BrResClassFindMany () ,;, fail to find any resource class. 


(See fwproto.h fora precise declaration) 


The typedef 


br_resource_class * br_resclass_find_cbfn(const char *) Find(whenBrResClassFind () 


fails) 


Specification 


CBFnResClassFind () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 
Result: 


Remarks: 


See Also: 


330 


An application defined call-back function used when BrResClassFind () 33. or 
BrResClassFindMany () 33. fail. 


br_resource_class* BR_CALLBACK 
CBFnResClassFind(const char* name) 


const char * name 
The search pattern supplied to BrResClassFind () 3:3. or 
BrResClassFindMany () 33. that did not match any resource class. 


BRender has completed initialisation. No resource class has an identifier that 
successfully matches the search pattern. 


Application defined. 


br_resource_class * 


Either return an existing resource class that is deemed appropriate for the search 
pattern, or NULL if there isn’t one. This value will be returned by 
BrResClassFind () 3, or BrResClassFindMany () 33.. 


This could either be used to supply a default resource or to create a resource class. 
If some resource classes were created on demand, then this function could search 
another list of available resource classes (but not yet created) and see if the pattern 
matched any of them, if it did, one of them could be registered and returned.Note 
that there is no way to supply more than one resource class. 


BrResClassFind () ;,., BrResClassFindMany () 33., 
BrResClassFindHook () 339. 
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br_resenum_chfn 


br resenum_cbfn 


‘The Call-Back Function 


This type defines a function, supplied to BrResChildEnum () ;), and to be called by it for each child 
resource block attached to a specific resource block. 


(See fwproto.h fora precise declaration) 


The typedef 


br_uint_32 br_resenum_cbfn(void *,void *) Enumerator 


Specification 


CBFnResEnum () 


Description: — An application defined call-back function accepting a resource block and an 
application supplied argument (as supplied to BrResChildEnum () <9). 


Declaration: br_uint_32 BR_CALLBACK CBFnResEnum(void* vres, void* arg) 
Arguments: void * vres 


One of the resource blocks attached as a child of the resource block supplied to 
BrResChildEnum () 5). 


void * arg 
The argument as supplied to BrResChildEnum () 5. 
Preconditions: | BRender has completed initialisation. 
Effects: | Application defined. 
If blocks are attached to the parent during the enumeration, they may not be 


included in the enumeration. Only the current, supplied child resource block 
should be detached or freed (if desired). 


Result! br _uint_32 


Any non-zero value will terminate the enumeration and be returned by 
BrResChildEnum () 5). Return zero to continue the enumeration. 


See Also: BrResChildEnum () ,,, BcResClassEnum () 3. 
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br_resource_class 


br resource class 


The Structure 


This structure is used for application defined resource classes. 


Once the structure 1s initialised, it is registered using BrResClassAdd () ,,;, thereafter allowing 
application defined memory or resource classes to be used. 


The typedef 


(See brmem.h for precise declaration and ordering) 


Primary 

br_uint_8 res_class Resource memory class 
br_resourcefree_cbfn* free_cb Resource destructor 
Supplementary 

char * identifier Resource class name 
Related Functions 


Resource Management 


See BrResAllocate () ,., BrResFree () ;,, BrResAdd () ,., BcResRemove () ;,, BrResStrDup () 4o, 
BrResSize() 5), BrResClass () ,,, BeResChildEnum () <9. 


Memory Management 


See BrMemAllocate () ,,, BeMemCalloc() ;,, BreMemInquire () .;, BrMemF ree () <., 
BrMemStrDup () 5. 


Related Structures 


Memory Management 


See br_allocator,,,. 
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br_resource_class 


Members 
Primary 


br_uint_8 res_class 


The memory class of the new resource class. See Memory Classes for a description of possible values. 
Only values between BR_MEMORY_APPLICATION+1 and BR_MEMORY_MAX-1 (inclusive) should be 
used. 


br_resourcefree_cbhfn * free_ch 


This is a pointer to the destructor function (See br_resourcefree_cbfn,,,) it may be NULL if not 
required. Note that this function is not used to free the memory of the resource. It is simply an 
opportunity for the application to perform any other housekeeping functions indicated by the 
destruction of the resource. The resource is destroyed after the destructor returns. 


For example, a user defined resource may be of structures containing pointers to reference counted 
(non-resource) items. In such a case, the referenced item will need to be dereferenced. 


Supplementary 


char * identifier 


Pointer to unique, zero terminated, character string (or NULL if not required). A string constant is 
recommended. The alternative is to use something like: 
my_res_class=BrResAllocate (NULL, sizeof (br_resource_class), 
BR_MEMORY_RESOURCE_CLASS) ; 
my_res_class—>identifier=BrResStrDup (my_res_class, MyClass”); 


Operations 


BrResClassAdd () 


Description: | Create a new resource class. 
Declaration: br_resource_class* BrResClassAdd(br_resource_class* rclass) 
Arguments: br_resource_class * rclass 


Anon-NULL pointer toa resource class. The res_class member of rclass 
must be set to a valid, unused class ID between BR_MEMORY_APPLICATION+1 and 
BR_MEMORY_MAX~—1 (inclusive). 


Preconditions: Between BrBegin(),, & BrEnd() ,). 
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br_resource_class 


Result: 


Remarks: 


br_resource_class * 


Returns a pointer to the resource class or NULL if unsuccessful. 


Remember, that rclass must point to a resource class structure that will remain 
valid until the class is removed. 


BrResClassAddMany () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Result: 


Remarks: 


Create several new resource classes. 


br_uint_32 


BrResClassAddMany (br_resource_class* const* items, int n) 


br_resource_class * const * items 
Anon-NULL pointer to a series of pointers to resource classes. The res_class 
member of each resource class structure pointed to by items must be set toa 


valid, unused class ID between BR_MEMORY_APPLICATION+1 and 
BR_MEMORY_MAX~—1 (inclusive). 


int n 

Number of new resource classes to create. 

Between BrBegin () ,, & BrEnd() ,,. 

br_uint_32 

Returns the number of resource classes successfully created. 


Remember, that each resource class structures must remain valid until it is 
removed. 


BrResClassRemove () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Result: 


Remove a resource class from use. 


br_resource_class* 
BrResClassRemove (br_resource_class* rclass) 


br_resource_class * rclass 


Anon-NULL pointer to a resource class (that has been previously created using 
BrResClassAdd () ,;;). 


Between BrBegin () ,) & BrEnd() ,,. 


br_resource_class * 


Returns a pointer to the removed resource class. 


BrResClassRemoveMany () 


Description: 


334 


Remove a number of resource classes from use. 
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br_resource_class 


Declaration:  br_uint_32 
BrResClassRemoveMany (br_resource_class* const* items, int n) 


Arguments: br_resource_class * const * items 


Anon-NULL pointer to an array of pointers to resource classes (all having 
previously been created using BrResClassAdd () ;3;). 


int n 
Number of resource classes to remove from use. 
Preconditions: Between BrBegin(),, & BrEnd () ,,- 
Result! br_uint_32 


Returns the number of resource classes successfully removed from use. 


Copy/Assign 


Beware of copying the structure if identifier has been allocated from the heap. Do not use the 
same structure for different resource classes. 


Access & Maintenance 


While a current resource class, the members should not be changed. No maintenance required. 


Referencing & Lifetime 


The structure must remain valid until the class is removed using BrResClassRemove () ;;,. BRender 
will not necessarily make a copy of the br_resource_class,,, structure. 


Initialisation 


The members should be set before the structure is passed to BrResClassAdd () 335. 


Construction & Destruction 


The structure should ideally be statically constructed, but could be constructed and destroyed as in 
the following code: 
braresource class* my_res_class; 
my_res_class=BrResAllocate (NULL, sizeof (br_resource_class), 
BR_MEMORY_RESOURCE_CLASS) ; 
.../* Set members */ 
#define MY_RES_CLASS BR_MEMORY_APPLICATION+1 
my_res_class-—>res_class=MY_RES_CLASS; 
my_res_class-—>free_cb=NULL; 
my_res_class—>identifier="MyResClass”; 


BrResClassAdd(my_res_class) ; 
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br_resource_class 


BrResFree (my_res_class) ; 


Supplementary 


The identifier may be used to specify a resource class by name. Not recommended for intensive 
use. Locate resources, and keep a record of pointers. The following functions provide searching, 
counting and enumeration facilities for resource classes. 


BrResClassFind () 


Description: 


Declaration: 


Arguments: 


Result: 


Find a resource class in the registry by name. A call-back function can be set up to 
be called if the search is unsuccessful. The search pattern can include the standard 
wild cards ‘*’ and ‘?’. 


br_resource_class* BrResClassFind(const char* pattern) 
const char * pattern 

Search pattern. 

br_resource_class * 


Returns a pointer to the resource class if found, otherwise NULL. Ifa call-back 
exists and is called, the call-back’s return value is returned. 


BrResClassFindMany () 


Description: 


Declaration: 


Arguments: 


Result: 


336 


Find a number of resource classes in the registry by name. The search pattern can 
include the standard wild cards ‘*’ and ‘?’. 


br_uint_32 BrResClassFindMany (const char* pattern, 
br_resource_class** items, int max) 


const char * pattern 

Search pattern. 

br_resource_class ** items 

A pointer to an array of pointers to resource classes. 
int max 

The maximum number of resource classes to find. 
br_uint_32 


Returns the number of resource classes found. The pointer array is filled with 
pointers to the resource classes. 
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br_resource_class 


BrResClassFindHook () 


Description: 


Declaration: 


Arguments: 


Result: 


Example: 


Set up a resource class find call-back. If BrResClassFind () ,,.is unsuccessful and 
a call-back has been set up, the call-back is passed the search pattern as its only 
argument. The call-back should then return a pointer to a substitute or default 
resource class. 


br_resclass_find_cbfn* 
BrResClassFindHook (br_resclass_find_cbfn* hook) 


br_resclass_find_cbfn * hook 
A pointer to a call-back function. 


br_resclass_find_cbfn * 


Returns a pointer to the old call-back function. 


br_resource_class BR_CALLBACK * example_callback(char* pattern) 


{ 


br_resource_class default; 


return (&default); 


br_resource class *re; 


BrResClassFindHook (&example_callback) ; 


rc = BrResClassFind(“non_existant_class”); 


BrResClassCount () 


Declaration: 


Description: 


Arguments: 


Result: 


br_uint_32 BrResClassCount (const char* pattern) 


Count the number of resource classes in the registry whose names match a given 
search pattern. The search pattern can include the standard wild cards ‘*’ and ‘?’. 


const char * pattern 
Search pattern. 
br_uint_32 


Returns the number of resource classes matching the search string. 
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br_resource_class 


BrResClassEnum () 


Description: 


Declaration: 


Arguments: 


Result: 


Example: 


338 


Call a call-back function for every resource class matching a given search pattern. 
The call-back is passed a pointer to each matching resource class, and its second 
argument is an optional pointer supplied by the user. The search pattern can 
include the standard wild cards ‘*’ and ‘?’. The call-back itself returns a 
br_uint_32,;, value. The enumeration will halt at any stage if the return value 
is non-zero. 


br_uint_32 BrResClassEnum(char* pattern, 
br_resclass_enum_cbfn* callback, void* arg) 


char * pattern 

Search pattern. 

br_resclass_enum_cbfn * callback 

A pointer to a call-back function. 

void * arg 

An optional argument to pass to the call-back function. 
br_uint_32 


Returns the first non-zero call-back return value, of zero if all resource classes are 
enumerated. 


br_uint_32 BR_CALLBACK example_callback (br_resource_class* item, 


void* arg) 


br_uint_32 value; 
return(value) ; 
br_uint_32 ev; 


ev = BrResClassEnum(“pattern”, &example_callback, NULL) ; 
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br_resourcefree_cbhfn 


br resourcefree cbfn 


‘The Call-Back Function 


This type defines a ‘destructor’ function, optionally specified in the resource class descriptor 
br_resource_class,,,, that is called just before a resource block is freed. 


(See fwproto.h fora precise declaration) 


The typedef 


void br_resourcefree_cbfn(void*,br_uint8,br_size_t) Destructor 


Specification 


CBFnResourceF ree () 


Description: — An application defined call-back function accepting details of a resource block just 
before it will be freed. 


Declaration: void BR_CALLBACK CBFnResourceFree(void* res, 
br_uint_8 res_class, br_size t size) 


Arguments: void * res 

The resource block about to be freed. 
br_uint_8 res_class 
The memory class of the resource block’s resource class. 
br_size t size 
The size of the resource block (useful for arrays). 

Preconditions: | BRender has completed initialisation. 

Effects: Application defined. 

Do not free the block — this will be performed after the function returns. This 


function will also be subsequently called for any child resource blocks still 
attached. 


See Also: BrResFree() 5. 
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br_scalar 


br scalar 


The Integral Type 


The br_scalar,,, type is the general numerical representation used by BRender. Under the fixed 
point library, br_scalar,,, isa 32 bit fixed point number (sign + 15 bit integer + 16 bit fraction), and 
can represent numbers between approximately -32768 and +32768. Under the floating point library, 
br_scalar,,, isa float, and can represent numbers between approximately -3.4e38 and +3.4e38. 


Use br_scalar,,, instead of int, float or double, in all numerical modelling aspects of an application 
program. 


The typedef 


(See scalar.h for precise declaration) 


float br_scalar Floating point 
br_fixed_ls br_scalar Fixed — Long Signed(15.16) 
Arithmetic 


No standard arithmetic operators are supported. The following macros should be used instead. All 
arguments and return values are of type br_scalar,,, (except where otherwise stated). 


Macros for Standard Operations 
BR_ADD (a,b) 

Return the equivalentof a + b. 
BR_SUB (a,b) 


| 
jon 


Return the equivalent of a 
BR_CONST_MUL (a, x) 


Return the equivalent of a * (where x is a numeric constant). 


™ 


BR_MUL (a,b) 

Return the equivalentof a * b. 
BR_SQR (a) 

Return the equivalent of a * a. 
BR_RCP (a) 

Return the equivalentof 1.0 / a. 
BR_CONST_DIV (a, x) 


Return the equivalent of a / (where x is a numeric constant). 


x 


BR_DIV (a,b) 


Return the equivalent of a / b. 
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BR_DIVR (a,b) 


br_scalar 


Return the equivalent of a / b (rounding toward zero instead of negative 


infinity’). 
BR_MULDIV (a,b,c) 


Return the equivalentof a * b/c. 


Macros for Standard Functions 
BR_ABS (a) 


Return the equivalent of fabs( a 
BR_POW (a,b) 


) 


Return the equivalent of pow( a, b ) 


BR_SQRT (a) 


Return the equivalent of sqrt ( a 


) 


Macros for Vector and Matrix Oriented Arithmetic 


For Two Pairs of Operands 
BR_SQR2 (a,b) 


Return the equivalentof a * a + 
BR_LENGTH2 (a,b) 


Return the equivalent of sqrt( a * a+b 


BR_RLENGTH2 (a,b) 


Return the equivalent of ( 1.0 / 
BR_MAC2 (a,b,c,d) 


Return the equivalentof a * b + 
BR_MAC2DIV(a,b,c,d,e) 


Return the equivalent of ( a * b 


For Three Pairs of Operands 
BR_SQR3 (a,b,c) 


Return the equivalentof a * a + 
BR_LENGTH3 (a,b,c) 


Return the equivalent of sqrt( a 
BR_RLENGTH3 (a,b,c) 


Return the equivalent of ( 1.0 / 





b&b 


sqrt ( 


eee 5 CL) 


4 Ups Rebbe * xe) 


* Sometimes this difference between BR_DIV() and BR_DIVR() can be important when dealing with fixed 


point values. 
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br_scalar 


BR_MAC3(a,b,c,d,e, £) 


Return the equivalentofa * b+c*d+ter*f 
BR_MAC3DIV(a,b,c,d,e,f£,g) 

Return the equivalentof ( a*b+c*d+e*f)/g. 
For Four Pairs of Operands 
BR_SOR4 (a,b,c, d) 

Return the equivalentofa * a+b* bt+tc*ct+ada*d 


BR_LENGTH4 (a,b,c, d) 
Return the equivalentof sqrt( a*a+b* bt+tcec*c+da*d) 
BR_RLENGTH4 (a,b,c, d) 


Return the equivalentof (1.0 / sqrt(a*a+tb*b+e*ctd 
*d)) 

BR_MAC4 (a,b,c,d,e,£,g,h) 
Return the equivalentofa * b+c*d+e*ftg*h. 


BR_MAC4DIV(a,b,c,d,e,f£,g,h,i) 


0) 
+ 
Kh 

a 

Q 
* 
or 


Return the equivalentof ( a * b +c * d + f- i- 
Comparison 


Equality and comparison with zero are valid. Other standard comparison operators may be 
implemented by macros in future versions, but are currently valid. 


Conversion 


From Numeric Constants 
BR_SCALAR (x) 


Convert x from any numeric constant to scalar type. Also see BR_CONST_MUL () 
and BR_CONST_DIV(). 


BR_SCALAR_ EPSILON 


Smallest representable positive scalar value. 
BR_SCALAR_MIN 


Largest representable negative scalar value. 
BR_SCALAR_MAX 


Largest representable positive scalar value. 
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br_scalar 


From Integral Types 


br_scalar BrIntToScalar(int i) 


Converts i from any integer type to scalar type. 


br_scalar BrFloatToScalar(int i) 


Converts i from float ordouble type to scalar type. 


From Other BRender Types 


br_scalar BrAngleToScalar(br_angle a) 


Converts a from angle type to scalar type. 


br_scalar BrFixedToScalar(br_fixed_ls f) 


Converts £ from fixed type to scalar type. 


br_scalar BrFractionToScalar (br_fraction f) 


Converts £ from fraction type to scalar type. 


br_scalar BrUFractionToScalar(br_ufraction u) 


Converts u from unsigned fraction type to scalar type. 


To Integral Types 


int BrScalarToInt (br_scalar s) 


Converts s from scalar type to int. 


float BrScalarToFloat (br_scalar s) 


Converts s_ from scalar type to float. 


To Other BRender Types 


br_angle BrScalarToAngle(br_scalar s) 


Converts a from scalar type to angle type. 


br_fixed_ls BrScalarToFixed(br_scalar s) 


Converts s_ from scalar type to fixed type. 


br_ fraction BrScalarToFraction (br scalar s) 


Converts £ from scalar type to fraction type. 


br_ufraction BrScalarToUFraction(br_ scalar s) 


Converts u_ from scalar type to unsigned fraction type. 


Copy/Assign 


Only assign zero, or scalars. Use conversions in all other cases. 
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br_size_t 


br size t 


The Integral Type 


BRender’s size type — in case the target environment does not define a size_t type. Use this type 
to represent sizes, as returned by the sizeof () operator. 


The typedef 


(See compiler.h for precise declaration) 
unsigned int br_size t Generic size type 


Arithmetic 


All standard C arithmetic operators are valid (though not necessarily sensible) as with standard 
integer types. 


Comparison 


All standard C comparison operators are valid as with standard integer types. 


Conversion 


Use casts as with any other standard C type. 


Copy/Assign 


Use as is the convention with the size_t type. 
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br_table_enum_cbfn 


br table enum _cbfn 


‘The Call-Back Function 


This type defines a function, supplied to BrTableEnum () ,.,, and to be called by it for a selection of 


tables. 


The typedef 


(See fwproto.h fora precise declaration) 


br_uint_32 


br_table_enum_cbfn(br_pixelmap*, void*) Enumerator 





Specification 


CBFnTableEnum () 


Description: 


Declaration: 


Arguments: 


Preconditions: 
Effects: 


Result: 


See Also: 


An application defined call-back function accepting a table and an application 
supplied argument (as supplied to BrTableEnum () 557). 


br_uint_32 BR_CALLBACK CBFnTableEnum(br_pixelmap* table, 
void* arg) 

br_pixelmap * table 

One of the tables selected by BrTableEnum () 597. 

void * arg 

The argument supplied to BrTableEnum () 597. 

BRender has completed initialisation. 

Application defined. Avoid adding or removing tables within this function. 
br_uint_32 

Any non-zero value will terminate the enumeration and be returned by 
BrTableEnum() ,,,. Return zero to continue the enumeration. 


BrTableEnum () 5),, BrTableFind () 53. 
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br_table_find_cbfn 








br table find cbfn 


‘The Call-Back Function 


This type defines a function, registered with BrTableFindHook () 4,, to be called when 
BrTableFind () ». or BrTableFindMany () »9. fail to find any table. 


The typedef 


(See fwproto.h fora precise declaration) 


br_pixelmap* 


br_table_find_cbfn(const char*) Find (when BrTableFind () fails) 


Specification 


CBFnTableFind () 


Description: 
Declaration: 
Arguments: 
Preconditions: 


Effects: 
Result: 


Remarks: 


See Also: 


346 


An application defined call-back function used when BrTableFind () 59. or 
BrTableFindMany () 5»; fail. 


br_pixelmap* BR_CALLBACK CBFnTableFind(const char* name) 
const char * name 


The search pattern supplied to BrTableFind () 5, or BrTableFindMany () 50; 
that did not match any table. 


BRender has completed initialisation. No table has an identifier that successfully 
matches the search pattern. 

Application defined. 

br_pixelmap * 

Either return an existing table that is deemed appropriate for the search pattern, or 
NULL if there isn’t one. This value will be returned by BrTableFind () 59. or 
BrTableFindMany () 50. 

This could either be used to supply a default table or to create a table. If tables were 
created on demand, then this function could search another list of available tables 
(but not yet created) and see if the pattern matched any of them, if it did, one of 
them could be registered and returned. Note that there is no way to supply more 
than one table. 

BrTableFind () ,.., BrTableFindMany () ,.., BreTableFindHook () 599, 
BrTableFindFailedLoad () 5,9. 
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br_transform 


br transform 


The Structure 


This is BRender’s generic transformation type, primarily used to specify a transformation from one 
actor’s space to another’s. In an actor it represents the transform to be applied to co-ordinates (such 
as of a model) in its space to bring them into the co-ordinate space of its parent. 


The typedef 


(See transform.h for precise declaration and ordering) 


‘Transform Type 


br_uint_16 type Specifies how the transformation is represented. 


‘Translation Transform 
br_vector3 t.translate.t Translation for the Translation transform type 


Euler Transform 


br_vector3 t.euler.t Translation for the Euler transform type 

br_euler t.euler.e Euler angle set of the Euler transform type 

Look Up Transform 

br_vector3 t.look_up.t Translation for the Look Up transform type 

br_vector3 t.look_up. look Look-at vector for the Look Up transform type 

br_vector3 t.look_up.up Look-up vector for the Look Up transform type 

Quaternion Transform 

br_vector3 t.quat.t Translation for the Quaternion transform type 

br_quat t.quat.q Quaternion rotation for the Quaternion transform 
type 

Matrix Transform 

br_matrix34 t.mat Matrix34 for both Matrix transform types 


Related Functions 

Scene Modelling 

See BrActorToActorMatrix34 () g, and BrActorToScreenMat rix4 () gs. 
Related Structures 


Scene Modelling 


See br_actor,,. 
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Members 
Transform Type 


br_uint_16 type 


This member defines which other members of the transform structure have meaning. It should never 
be modified directly except for initialisation purposes. Refer to BrTransformToTransform () ;;; for 
details of how to convert from one transform to another. 


This member may have any one of the following values: 


Value Symbol Meaning 

BR_TRANSFORM_IDENTITY The transform is the identity. 

BR_TRANSFORM_TRANSLATION |The transform is a translation only (held int.translate.t). 

BR_TRANSFORM_EULER The transform is represented by a Euler angle set (t .euler.e) and 
a translation (t.euler.t). 

BR_TRANSFORM_LOOK_UP The transform is represented by a look-at vector 


(t. Look_up. look), an up vector (t . look_up.up) anda 
translation (t .look_up.t). 


BR_TRANSFORM_QUAT The transform is represented by a quaternion (t.quat.q)anda 
translation (t .quat.t). 
BR_TRANSFORM_MATRIX34 The transform is represented by a 3x4 affine matrix (t .mat), which 


is the most general representation. 











BR_TRANSFORM_MATRIX34_LP | The transform is represented by a 3x4 length preserving matrix 
(t.mat). 





Identity Transform 


The identity transform is engaged when type is set to BR_TRANSFORM_IDENTITY. This is effectively 
a NULL transform, making actors effectively share the same co-ordinate space as their parent. 


Translation Transform 


The translation transform is engaged when type is set to BR_TRANSFORM_TRANSLATION. This is 
solely a translation, i.e. no rotation or scaling is involved. 


br_vector3 t.translate.t 


This member only has meaning for this transform type’. It contains the vector representing the 
translation. 





* However, upon inspection of br_transform it can be seen that it is effective for all transforms apart from 


the identity. Use of this feature is for internal use only. 
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Euler Transform 


The Euler transform is engaged when type is set to BR_TRANSFORM_EULER. This consists of a three 
rotations about a combination of orthogonal axes and a translation (effectively applied after the 
rotations). See br_euler,,, for more information. 


br_vector3 t.euler.t 


This member contains the vector representing the translation component of the transform. 


br_vector3 t.euler.e 


This member contains the vector representing the rotation components of the transform. 


Look Up Transform” 


The Look Up transform effectively consists of a pair of rotations and a translation. The first rotation 
is defined about the origin between the negative z axis and the look vector. The second rotation is 
defined about the new z axis between the new positive x axis and the cross product of the up and 
look vectors. The translation is then applied. 


The Look Up transform is a convenient method of making an actor such as a camera point toward a 
particular position. It has the effect of making the actor’s negative’ z axis lie along the look vector, 
and its positive y axis lie in the plane defined by the up and look vectors (or more precisely, its 
positive x axis will lie along the cross product of the up and look vectors). Remember that the look 
and up vectors will be in the co-ordinate space of the actor’s parent and thus from its point of view, 
so if pointing at a particular actor, in order to compute look, that actor’s co-ordinates will also need 
to be transformed into the co-ordinate space of the parent (see BrActorToActorMat rix34 () 9). 
Incidentally, things can be simplified by using intermediate dummy actors (BR_ACTOR_NONE). 


The translation is applied at the end. 


br vector3: t..1lo0k_up.t 


This member contains the vector representing the translation component of the transform. 


br=Vectors bt. Look-up. look 


This member contains the vector that defines the rotation of the negative z axis. 


br_vector3 t.look_up.up 


This member contains the vector that defines the rotation about the look vector. 


Not represented by a separate BRender structure. 
+ Negative rather than positive in order to be consistent with the camera definition (which is the predominant 
actor expected to utilise the Look Up transform). 
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Quaternion Transform 


The unit quaternion transform represents a rotation about an arbitrary vector. 


br_vector3 t.quat.t 


This member contains the vector representing the translation component of the transform. 


bro Vectors C.quat.sq 


This member contains the vector representing the rotation component of the transform. 


Matrix Transforms 


Matrix transforms represent BRender’s most general form of transformation. See br_matrix34,,, 
for details of how matrix transformations are performed. 


BR_TRANSFORM_MATRIX34_LP isa slightly more specialised form which requires that the matrix have 
no scaling effect, 1.e. is length preserving. 


br _matrix34 t.mat 


This member contains the 3D affine matrix representing the entire transform. 


Arithmetic 


See BrMatrix34PreTransform() »),, BeMatrix34PostTransform () 5), and 
BrMatrix4PreTransform() ,,3. 


Conversion 


Also see BrMatrix34ToEuler () ..7, BrMatrix34ToQuat () »),, BrEulerToMatrix34 (),,; and 
BrQuat ToMatrix34 () 5,3. 


From Matrices and Other Transforms 


See BrMatrix34ToTransform() .. and BrTransformToTrans form () 353. 


To Matrices and Other Transforms 


See BrTransformToMatrix34 (),;, and BrTransformToTransform(),;, as described below. 
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BrTransformToMatrix34 () 


Description: | Convert a generic transform to a 3D affine matrix, that would have the same 
transformational effect. 


Declaration: void BrTransformToMatrix34 (br_matrix34* mat, 
const br_transform* xform) 


Arguments: br_matrix34 * mat 


A pointer to the destination matrix to receive the conversion. 


const br_ transform * xform 


A pointer to the source generic transform. 
Effects: | When the transform is the identity 


Uses to BrMatrix34Identity (),,, to re-initialise the destination matrix to the 
identity matrix. 


When the transform is a translation 


Uses to BrMatrix34Translate(),,, to re-initialise the destination matrix toa 
translation matrix. 


When the transform is a Euler angle set 


Calls BrEulerToMatrix34 (),,, and copies the transforms’ translation to the 
respective elements of the destination matrix. 


When the transform is a Look-Up 

The normalised and negated Look vector provides the third row of the matrix. 
The normalised cross product of this with the Up vector provides the first row. 
The cross product of these two rows provides the second row. 

The translation vector provides the fourth and last row. 

When the transform is a quaternion 


Calls BrQuat ToMatrix34 (),, and copies the transforms’ translation to the 
respective elements of the destination matrix. 


When the transform is a 3x4 matrix 
Directly copies the matrix from the source transform. 
When the transform is a 3x4 length preserving matrix 


Directly copies the matrix from the source transform. 


BrTransformToTransform () 


Description: | Convert from one transform to another, that would have the same transformational 
effect (where possible). 
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Declaration: void BrTransformToTransform(br_transform* dest, 
const br_transform* src) 


Arguments: br_transform * dest 


A pointer to the destination generic transform to receive the conversion. The 
destination’s type member is unchanged. 


const br_transform * src 
A pointer to the source generic transform to be converted. 
Effects: | When the transforms’ types are the same 
The transform structure is copied entire. 
When the destination transform is of matrix type 
Calls BrTransformToMatrix34 (),;,; then normalises if necessary. 
In other cases 


Converts the transform via an intermediate 3x4 matrix by first calling 
BrTransformToMatrix34 (),;,; and then BrMatrix34ToTransform () x. 


Remarks: — The transformation type in the destination transform must be set before conversion 
is performed’. 


In some cases it may not be possible to preserve all components of a transformation 
across the conversion. For example, a conversion of a matrix to a quaternion would 
lose any scaling or shearing components. 


Copy/Assign 


Although copy by structure assignment currently works, use BrTransformToTransform() 35; to 
ensure compatibility. 


Access & Maintenance 


Only the members corresponding to the currently set type should be accessed. The type should not 
be modified except for initialisation. The structure may be re-initialised, but any current references 
must be expecting this. No specific maintenance required, but refer to the descriptions of underlying 
structures for details of their maintenance requirements. 


Referencing & Lifetime 


This structure may be freely referenced, though take care when changing the type of a transform that 
any current references will take note. In the same vein, try to avoid referencing members of ‘live’ 
transforms. The structure should remain valid as long as required by any references. 





* This also applies to the order member of Euler transforms. 


3 5 2 Copyright © 1996 Argonaut Technologies Limited 


br_transform 


Initialisation 


First set the type member to the desired transform type and then initialise the appropriate members 
using their respective assignment methods. The simplest initialisation is to the Identity, which is also 


the only safe static initialisation. 
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br ufraction 


The Integral Type 


The br_ufraction,,, type can be used to represent numbers in the range [0,+1)". Although used 
internally, this type is not generally supported by the BRender API. One of the few places in which 
it is used is in specifying lighting coefficients of materials. 


Under the floating point library, br_ufraction,,, isa float. Under the fixed point library, 
br_ufraction,,, is a 16 bit unsigned fixed point number. 


The typedef 


(See scalar.h for precise declaration) 


float br_ufraction Floating point Unsigned Fraction 
br_fixed_luf br_ufraction Fixed — Long Unsigned Fraction(0.16) 
Arithmetic 


No standard operators are supported. No macros are provided. Convert to br_scalar,,, and use that 
type’s arithmetic macros instead. 


Comparison 


Equality and comparison with zero are valid. Other standard comparison operators may be 
implemented by macros in future versions, but are currently valid. 


Conversion 


From Numeric Constants 
BR_UFRACTION (x) 


Convert x from any numeric constant to br_ufraction,,,. 
BR_SCALAR_ EPSILON 


Smallest positive fractional value. 


From Integral Types 


To convert from integral types, use br_scalar,,, as an intermediary. 


* Maximum value is thus BR_ONE_LS-BR_SCALAR_EPSILON (in the fixed point library). 
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Frombr_scalar,,, 
br_ufraction BrScalarToUFraction(br_ scalar s) 


Converts s from br_scalar;,, to br_ufraction,;,. It is up to the application 
to ensure the value is in the required range. 


To Integral Types 


To convert to integral types, use br_scalar,,, as an intermediary. 


To br_scalar,,, 
br_scalar BrUFractionToScalar(br_ufraction f) 


Converts s from br_ufraction,,,tobr_scalar,,,. It is up to the application 
to ensure the value is in the required range. 


Copy/Assign 


Only assign zero, or fractions. Use conversions in all other cases. 
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br uint 8/16/32 


The Integral Type 


BRender’s unsigned integer types. Use this type where the integer word length is critical. 


The typedef 


(See compiler.h for precise declaration) 


unsigned char br_uint_8 8 bit unsigned integer 
unsigned short br_uint_16 16 bit unsigned integer 
unsigned long br_uint_32 32 bit unsigned integer 
Arithmetic 


All standard C arithmetic operators are valid as with standard integer types. 


Comparison 


All standard C comparison operators are valid as with standard integer types. 


Conversion 


Use casts as with any other standard C type. 


Copy/Assign 


Freely assign. Use as a standard C type, as this type is only concerned with ensuring specific sizes — 
not representation. 
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br vector2 


The Structure 


This is the two ordinate vector structure, typically used for 2D purposes. Functions are provided to 
allow it be used as though it were an integral type. 


The typedef 

(See vector.h for precise declaration and ordering) 

br_scalar v[2] Ordinates (O=x, 1=y) 
Related Functions 


Image Support 


See BrOriginToScreenxY () »;;, BrPoint ToScreenxY () ,,,, BcPointToScreenXYMany () 55., 


Maths 


See BrMatrix23App1yP () |, BreMatrix23ApplyV () ,;,, BeMatrix23TApplyP () 17, 
BrMat rix23TApplyV () 17. 


Related Structures 


See br_matrix23,,,, br_vertex,,,. 


Members 


br_scalar v[2] 


First and second ordinate. Conventionally, the first ordinate is the x-axis component, and the second, 
the y axis component. 


Arithmetic 


BrVector2Negate () 


Description: | Negate a vector and place the result in a second destination vector. Equivalent to 
the expression: 


Vv, e-V>, 


Declaration: void BrVector2Negate(br_vector2* v1, const br_vector2* v2) 
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Arguments: br_vector2 * v1 


A pointer to the destination vector (may be same as source). 


const br_vector2 * v2 


A pointer to the source vector. 


BrVector2Add () 


Description: | Add two vectors and place the result in a third destination vector. 
Equivalent to the expression: 
vi = V> + V3 


Declaration: void BrVector2Add(br_vector2* v1, const br_vector2* v2, 
const br_vector2* v3) 


Arguments: br_vector2 * v1 


A pointer to the destination vector (may be same as either source). 


const br _vector2 * v2 


A pointer to the first vector of the sum. 


const br _vector2 * v3 


A pointer to the second vector of the sum. 


BrVector2Accumulate () 
Description: — Add one vector to another. Equivalent to the expression: 
V,;eVit+V> 


Declaration: void BrVector2Accumulate (br_vector2* v1, 
const br_vector2* v2) 


Arguments: br_vector2 * v1 


A pointer to the accumulating vector (may be same as v2). 


const br _vector2 * v2 


A pointer to the vector to add. 


BrVector2Sub () 


Description: Subtract one vector from another and place the result in a third destination vector. 


Equivalent to the expression: 


Vi =V2.-V3 
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Declaration: void BrVector2Sub(br_vector2* v1, const br_vector2* v2, 
const br_vector2* v3) 


Arguments: br_vector2 * v1 


A pointer to the destination vector (may be same as v1 or v2). 


const br_vector2 * v2 


A pointer to the additive vector. 


const br_vector2 * v3 


A pointer to the subtractive vector. 


BrVector2Scale () 


Description: Scale a vector bya scalar and place the result in a destination vector. Equivalent to 
the expression: 


Vi co SV> 
Declaration: void BrVector2Scale(br_vector2* v1, const br_vector2* v2, 
br scalar s) 
Arguments: br_vector2 * v1 


A pointer to the destination vector (may be same as source). 


const br_vector2 * v2 


A pointer to the source vector. 


br_scalar s 


Scale factor. 


BrVector2InvScale () 


Description: Scale a vector by the reciprocal of a scalar and place the result in a destination 
vector. Equivalent to the expression: 
-l 
vi eS V> 
Declaration: void BrVector2InvScale(br_vector2* v1, const br_vector2* v2, 
br_scalar s) 
Arguments: br_vector2 * v1 


A pointer to the destination vector (may be same as source). 


const br_vector2 * v2 


A pointer to the source vector. 


br_scalar s 


Reciprocal scale factor. 
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BrVector2Dot () 


Description: — Calculate the dot product of two vectors. Equivalent to the expression: 
vi * V> 


Declaration: br_ scalar BrVector2Dot (const br_vector2* v1, 
const br_vector2* v2) 


Arguments: const br_vector2 * v1 


Pointer to left hand vector (may be same as v2). 


const br_vector2 * v2 


Pointers to right hand vector. 


Result! br_scalar 
Returns the dot product of the two source vectors. Equivalent to: 


(xX, ¥1) + (Xy Yo) = XX. + V2 


BrVector2Length () 


Description: Calculate the length of a vector. Equivalent to the expression: 
Ml 


Declaration: br_scalar BrVector2Length(const br_vector2* v1) 


Arguments: const br_vector2 * vl 


A pointer to the source vector. 


Result! br scalar 


Returns the length of the vector. Equivalent to: 


ae) Sa 


See Also: BrVector2LengthSquared () ,; 


BrVector2LengthSquared () 


Description: Calculate the squared length of a vector. Equivalent to the expression: 
2 
Mal 
or 
vi vi 


Declaration: br_scalar BrVector2LengthSquared(const br_vector2* v1) 
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Arguments: const br_vector2 * vl 
A pointer to the source vector. 
Result: br_scalar 


Returns the squared length of the vector. Equivalent to: 


ee PO Sart 


See Also: BrVector2Length () x, 


BrVector2Normalise () 


Description: | Normalise a vector and place the result in a destination vector. Equivalent to the 
expression: 


Declaration: void BrVector2Normalise(br_vector2* vl, 
const br_vector2* v2) 


Arguments: br_vector2 * v1 
A pointer to the destination vector (may be same as source). 
const br _vector2 * v2 


A pointer to the source vector. 


Remarks: _ If the source vector’s length is zero’ the unit vector along the x axis is stored at the 
destination instead. 


Copy/Assign 
Although copy by structure assignment currently works, use BrVector2Copy () 3, to ensure 
compatibility. 


BrVector2Copy () 
Description: | Copy a vector. Equivalent to the expression: 
Vie=V> 


Declaration: void BrVector2Copy (br_vector2* v1, const br_vector2* v2) 





* Or, in the fixed point library, too close to zero, i.e. less than or equal to 2*BR_SCALAR_EPSILON. 
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Arguments: br_vector2 * v1 


A pointer to the destination vector (may be same as source). 


const br_vector2 * v2 


A pointer to the source vector. 


Referencing & Lifetime 


This structure may be freely referenced, though take care if there is potential to supply the same 
vector as more than one argument to the same function. 


Initialisation 
The following macro may be used as a static initialiser. 
BR_VECTOR2 (a,b) 


Macro expands to {BR_SCALAR(a),BR_SCALAR(b) }. 


All other initialisation should use the functions, BrVector2Set () ,,,, BrVector2Set Int () x5, 
BrVector2SetFloat (),; or BrVector2Copy () 364. 


BrVector2Set () 


Description: | Set a vector with a pair of scalars. 
Declaration: void BrVector2Set (br_vector2* vl, br_scalar sl, br_scalar s2) 
Arguments: br_vector2 * v1 

A pointer to the destination vector. 

br_scalar sl 

The first vector element (x axis component). 

br_scalar s2 

The second vector element (y axis component). 


Example: 


br_vector2 *va; 


BrVector2Set (va, BR_SCALAR(1.0),BR_SCALAR(-1.0)); 


BrVector2SetFloat () 


Description: Seta vector froma pairof standard C floating point numbers. 
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Declaration: void BrVector2SetFloat (br_vector2* vl, float £1, float f2) 


Arguments: br_vector2 * v1 


A pointer to the destination vector. 
float f1 


The first vector element (x axis component). 
float £2 


The second vector element (y axis component). 


Example: 


br_vector2 *va; 


BrVector2Set (va,1.f,-1.f); 


BrVector2SetIint () 


Description: Seta vector from a pair of standard C integers. 
Declaration: void BrVector2SetInt (br_vector2* vl, int il, int i2) 
Arguments: br_vector2 * v1 

A pointer to the destination vector. 

int il 

The first vector element (x axis component). 

int i2 

The second vector element (y axis component). 


Example: 


br_vector2 *va; 


BrVector2Set (va,1,-1); 
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br vector3 


The Structure 


This is the three ordinate vector structure, typically used for 3D calculations. Functions are provided 
to allow it be used as though it were an integral type. 


The typedef 


(See vector.h for precise declaration and ordering) 
br_scalar v[3] Ordinates (0=x, 1=y, 2=3) 


Related Functions 


Image Support 


See BrOriginToScreenxXYZO () ,.;, BcPoint ToScreenXYZO () 557, 
BrPointToScreenXYZOMany () 55¢. 


Maths 


See BrMatrix34[PrelPost ]Rotate () jx99129s) BrMatrix[3414][TJApply[VIP] () 1193-:o61219-2227 


Related Structures 


See br_matrix23,,,, br_matrix34,,,, br_model,,,, br_vertex,,,, br_transform,,, 
br_bounds j9¢. 


Members 


br_ scalar v[3] 


First, second and third ordinate. Conventionally, the first ordinate is the x-axis component, the 
second, the y axis component, and the third, the z axis component. Remember that BRender has a 
right handed co-ordinate system and so, with the x axis positive to the right, and the y axis positive 
upwards, the z axis is therefore positive toward you (typically, the z axis points out of the screen). 
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Arithmetic 


BrVector3Negate () 


Description: | Negate a vector and place the result in a second destination vector. Equivalent to 
the expression: 


Vi co —V> 
Declaration: void BrVector3Negate (br_vector3* v1, const br_vector3* v2) 
Arguments: br_vector3 * v1 


A pointer to the destination vector (may be same as source). 


const br_vector3 * v2 


A pointer to the source vector. 


BrVector3Add () 


Description: Add two vectors and place the result in a third destination vector. 
Equivalent to the expression: 
vi = V> + V3 


Declaration: void BrVector3Add(br_vector3* vl, const br_vector3* v2, 
const br_vector3* v3) 


Arguments: br_vector3 * v1 


A pointer to the destination vector (may be same as either source). 


const br_vector3 * v2 


A pointer to the first vector of the sum. 


const br_vector3 * v3 


A pointer to the second vector of the sum. 


BrVector3Accumulate () 


Description: | Add one vector to another. Equivalent to the expression: 
vi co Vi + V> 


Declaration: void BrVector3Accumulate (br_vector3* vl, 
const br_vector3* v2) 
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Arguments: 


br_vector3 * vl 


A pointer to the accumulating vector (may be same as v2). 


const br_vector3 * v2 


A pointer to the vector to add. 


BrVector3Sub () 


Description: 


Declaration: 


Arguments: 


Subtract one vector from another and place the result in a third destination vector. 


Equivalent to the expression: 


Vi =V2-V3 


void BrVector3Sub(br_vector3* vl, const br_vector3* v2, 
const br_vector3* v3) 


br_vector3 * vl 


A pointer to the destination vector (may be same as v2 or v3). 


const br_vector3 * v2 


A pointer to the additive vector. 


const br_vector3 * v3 


A pointer to the subtractive vector. 


BrVector3Scale () 


Description: 


Declaration: 


Arguments: 


366 


Scale a vector by a scalar and place the result in a destination vector. Equivalent to 
the expression: 


Vv, = SV> 


void BrVector3Scale(br_vector3* v1, const br_vector3* v2, 
br scalar s) 


br_vector3 * vl 


A pointer to the destination vector (may be same as source). 


const br_vector3 * v2 


A pointer to the source vector. 


br_scalar s 


Scale factor. 
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BrVector3InvScale () 


Description: Scale a vector by the reciprocal of a scalar and place the result in a destination 
vector. Equivalent to the expression: 


=i 
V,E5 Vp 


Declaration: void BrVector3InvScale (br_vector3* v1, const br_vector3* v2, 


br_scalar s) 


Arguments: br_vector3 * v1 


A pointer to the destination vector (may be same as source). 


const br_vector3 * v2 


A pointer to the source vector. 


br_scalar s 


Reciprocal scale factor. 


BrVector3Dot () 


Description: Calculate the dot product of two vectors. Equivalent to the expression: 
vi 5 V> 
Declaration: br_ scalar BrVector3Dot (const br_vector3* v1, 
const br_vector3* v2) 
Arguments: const br_vector3 * vl 


Pointer to left hand vector (may be same as v2). 


const br_vector3 * v2 


Pointers to right hand vector (may be same as v1). 


Result! br scalar 


Returns the dot product of the two source vectors. Equivalent to: 


(X, Vy 2) + (X2 Vo 2%) = XX. + VWpV2 + 2422 


BrVector3Cross () 


Description: | Calculate the cross product of two vectors and store the result in a destination 
vector. Equivalent to the expression: 


VV, <=V)XV; 


Declaration: void BrVector3Cross (br_vector3* v1, const br_vector3* v2, 
const br_vector3* v3) 
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Arguments: br_vector3 * v1 


Pointer to destination vector (must be different from both v1 and v2). 


const br_vector3 * v2 


Pointer to left hand vector. 


const br_vector3 * v3 
Pointers to right hand vector. 


Remarks: — The cross product of the two source vectors is equivalent to: 


(X_ Yo 2%) X(%3 V3 2%) =(V2%3— 23 2X3 —X2Zz_—4X0 3 — Vo 3) 


BrVector3Length () 
Description: Calculate the length of a vector. Equivalent to the expression: 
Iv 


Declaration: br_scalar BrVector3Length (const br_vector3* v1) 


Arguments: const br_vector3 * v1 


A pointer to the source vector. 


Result: br scalar 


Returns the length of the vector. Equivalent to: 


a 2 ae eee 
(xy yy Z| = fx ty +2 


See Also: BrVector3LengthSquared () ,7, 


BrVector3LengthSquared () 


Description: — Calculate the squared length of a vector. Equivalent to the expression: 
2, 
Iv, 
or 
Vi = Vi 


Declaration: br_scalar BrVector3LengthSquared (const br_vector3* v1) 
Arguments: const br_vector3 * vl 
A pointer to the source vector. 
Result: br_scalar 


Returns the squared length of the vector. Equivalent to: 


Oe A DR ie 
(x, yi Z1)| SX, ty, ty 


See Also: BrVector3Length () 57, 
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BrVector3Normalise () 


Description: | Normalise a vector and place the result in a destination vector. Equivalent to the 
expression: 


Vo 


vi = 
Ae, 
Declaration: void BrVector3Normalise (br_vector3* vl, 
const br_vector3* v2) 
Arguments: br_vector3 * v1 
A pointer to the destination vector (may be same as source). 
const br_vector3 * v2 
A pointer to the source vector. 


Remarks: _ If the source vector’s length is zero’ the unit vector along the x axis is stored at the 
destination instead. 


BrVector3NormaliseQuick () 


Description: | Normalise a vector with non-zero length and place the result ina destination vector. 
Equivalent to the expression: 


Vo 


1 Wi] 


Declaration: void BrVector3NormaliseQuick (br_vector3* vl, 
const br_vector3* v2) 


Arguments: br_vector3 * v1 


A pointer to the destination vector (may be same as source). 


const br_vector3 * v2 


A pointer to the source vector. 


Remarks: | No check made for zero length, hence quicker. 


* Or, in the fixed point library, too close to zero, i.e. less than or equal to 2* BR_SCALAR_EPSILON. 
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BrVector3NormaliseLP () 


Description: | Normalise a vector with non-zero length using low precision” arithmetic and place 
the result in a destination vector. Equivalent to the expression: 
-l 
Vi co \v.| V> 
Declaration: void BrVector3NormaliseLP (br_vector3* v1, 
const br_vector3* v2) 
Arguments: br_vector3 * v1 


A pointer to the destination vector (may be same as source). 


const br _vector3 * v2 


A pointer to the source vector. 


Remarks: | No check is made for zero length. The destination vector will be left unchanged if 
the reciprocal of length of the vector is zero. 


Copy/Assign 


Although copy by structure assignment currently works, use BrVector3Copy () ,,, to ensure 
compatibility. 


BrVector3Copy () 
Description: | Copy a vector. Equivalent to the expression: 
Vie=V> 
Declaration: void BrVector3Copy (br_vector3* vl, const br_vector3* v2) 
Arguments: br_vector3 * v1 


A pointer to the destination vector (may be same as source). 


const br_vector3 * v2 


A pointer to the source vector. 


Referencing & Lifetime 


This structure may be freely referenced, though take care if there is potential to supply the same 
vector as more than one argument to the same function. 





* Thus LP in the function name - do not be confused with the use of this mnemonic for ‘length preserving’. 
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Initialisation 
The following macro may be used as a static initialiser. 
BR_VECTOR3 (a,b,c) 


Macro expands to {BR_SCALAR (a) , BR_SCALAR(b) , BR_SCALAR (Cc) }. 


All other initialisation should use the functions, BrVector3Set () ,,,, BrVector3Set Int () 5,5, 
BrVector3SetFloat ()3,, or BrVector3Copy () 3,3. 


BrVector3Set () 


Description: Set a vector with a triple of scalars. 


Declaration: void BrVector3Set (br_vector3* vl, br_scalar sl, br_scalar s2, 
br_ scalar s3) 


Arguments: br_vector3 * v1 
A pointer to the destination vector. 
br_scalar sl 
The first vector element (x axis component). 
br_scalar s2 
The second vector element (y axis component). 
br_scalar s3 
The third vector element (z axis component). 


Example: 
br_vector3 *va; 


BrVector3Set (va, BR_SCALAR(1.0),BR_SCALAR(-1.0),BR_SCALAR(2.0)); 


BrVector3SetFloat () 


Description: Seta vector froma triple of standard C floating point numbers. 


Declaration: void BrVector3SetFloat (br_vector3* vl, float £1, float f2, 
float £3) 
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Arguments: 


Example: 


br_vector3 * vl 


A pointer to the destination vector. 
float f1 


The first vector element (x axis component). 
float £2 


The second vector element (y axis component). 
float £3 


The third vector element (z axis component). 


br_vector3 *va; 


BrVector3Set(va,1.f£,-1.f,1.5f£); 


BrVector3SetIint () 


Description: 
Declaration: 


Arguments: 


Example: 


Set a vector from a triple of standard C integers. 
void BrVector3SetInt (br_vector3* vl, 
br_vector3 * v1 

A pointer to the destination vector. 

int il 

The first vector element (x axis component). 
int i2 

The second vector element (y axis component). 
int i3 


The third vector element (z axis component). 


br_vector3 *va; 


BrVector3Set(va,1,-1,2); 


372 


int il, 


int i2, 


int i3) 
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br vector4 


The Structure 


This is the four ordinate vector structure, typically used to hold homogenous 3D co-ordinates. 
Functions are provided to allow it be used as though it were an integral type. 


The typedef 

(See vector.h for precise declaration and ordering) 

br_scalar v[4] Ordinates (O=x, 1=y, 2=3, 3=w) 
Related Functions 


See BrMatrix34TApply () 5, BeMatrix4[T]Apply[VIP] () 315.29 


Related Structures 


See br_matrix4,,;. 


Members 


br_scalar v[4] 


First, second, third and fourth ordinate. Conventionally, the first ordinate is the x-axis component, 
the second, the y axis component, the third, the z axis component, and the fourth, the divisor. 


Remember that BRender has a right handed co-ordinate system and so, with the x axis positive to the 
right, and the y axis positive upwards, the z axis is therefore positive toward you (typically, the z axis 
points out of the screen). 


Arithmetic 


BrVector4Dot () 
Description: — Calculate the dot product of two vectors. Equivalent to the expression: 
Vi : V> 


Declaration: br_ scalar BrVector4Dot (const br_vector4* v1, 
const br_vector4* v2) 


Arguments: const br_vector4 * vl 


Pointer to left hand vector (may be same as source). 
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const br_vector4 * v2 
Pointers to right hand vector. 
Result: br_scalar 


Returns the dot product of the two source vectors. Equivalent to: 


(X, Vy 2 Wy) (% Vo 2% Wz) = XX. + YY + 2% + WyWy 


Copy/Assign 
Although copy by structure assignment currently works, use BrVector4Copy () 3,, to ensure 
compatibility. 


BrVector4Copy () 
Description: | Copy a vector. Equivalent to the expression: 
Vv, =V> 
Declaration: void BrVector4Copy (br_vector4* v1, const br_vector4* v2) 
Arguments: br_vector4 * v1 
A pointer to the destination vector (may be same as source). 
const br_vector4 * v2 


A pointer to the source vector. 


Referencing & Lifetime 


This structure may be freely referenced, though take care if there is potential to supply the same 
vector as more than one argument to the same function. 


Initialisation 
The following macro may be used as a static initialiser. 
BR_VECTOR4 (a,b,c, d) 


Macro expands to 
{BR_SCALAR(a), BR_SCALAR(b),BR_SCALAR(c),BR_SCALAR (qd) }. 


All other initialisation should use member-wise initialisation or the function Brvector4Copy () 377. 
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br vertex 


Overview 


The vertex data structure, describing a single vertex in a model. 


The typedef 


(See model.h for precise declaration and ordering) 


Position 

br_vector3 Pp Co-ordinates of a point in model space 
‘Texture and Lighting 

br_vector2 map Texture co-ordinates of this vertex 
br_uint_8 index Colour index for pre-lit models 
br_uint_8 red, grn, blu True colour values for pre-lit model 
Related Functions 


See BrModelApplyMap (),,; and BrModelFitMap (),,. to set texture co-ordinates. See 
BrSceneModelLight (),;, to set pre-lit values. 


Related Structures 


See br_mode1,,, for the structure in which vertices are used. 


See br_material,,, for details of how pre-lighting information is used. 


Members 
Position 


br_vector3 p 


The co-ordinates of a point (in the model’s co-ordinate space) representing the vertex of a group of 
faces (typically triangular). 


For example, a cube has eight vertices. If it had unit side and was centred about (0,0,0), it would have 
vertices (0.5,0.5,0.5), (0.5,0.5,-0.5), etc. Faces are polygons (typically triangles) described in terms of 
a number of vertex indices. 
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Texture and Lighting 


br_vector2 map 


The 2D co-ordinates at which this vertex appears in an infinitely’ tiled texture map. 


br_uint_8 index 


Pre-computed lighting index at this vertex. See br_material,;, for how this relates to pre-lit 
materials. 


bE IES. red. grin, oi 


Pre-computed light level at this vertex (in terms of colour intensities"). See br_material,,, for how 
this relates to pre-lit materials. 


Copy/Assign 


Do not use structure assign. Use member-wise copy only. 


Access & Maintenance 


Members may be freely accessed. Models referencing vertices that are changed should be updated 
using BrModelUpdate(),,, before rendering. There are private members of vertices that are 
modified during BrModelUpdate () 54). 


Referencing & Lifetime 


Be careful of referencing vertices especially ones allocated by BrModelAllocate () ,,,, they are 
liable to be moved around during BrModelUpdate () ,,,, say. Vertices are generally only allocated as 
arrays completely describing a model. Always access using indexing from the model’s vertices 
member. 


Initialisation 


Use memset (,0, sizeof (br_vertex)) and set members as appropriate. Updating of models 
referencing initialised vertices will be needed before there are involved in rendering. 


Construction & Destruction 


Vertices may be constructed conventionally, but BR_MODF_KEEP_ORIGINAL must be specified in any 
model that refers to them. Otherwise use BrModelAllocate () 5,;. 





Subject of course to limits of by_scalar representation. 
+ Notall platforms support coloured lights. 
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Supplementary 


When constructed by BrModelAllocate ().,,, vertices are allocated from the “VERTICES” memory 
class. It is probably better to organise any enumeration around models (see br_model1,,,). 














Import & Export 


Vertices are included with model definitions. See br_model1,,, for details of import/export functions. 
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brfile advance _cbfn 


‘The Call-Back Function 


This type defines a stream advance function, primarily intended for the advance member of the 
br_filesystem,,, structure. 


The typedef 


(See brfile.h fora precise declaration) 
void brfile_advance_cbfn(br_size_t, void*) Advance 





Specification 


CBFnFileAdvance () 


Description: — An application defined call-back function advancing a file pointer a number of 
bytes through a binary stream. 


Declaration: void BR_CALLBACK CBFnFileAdvance (br_ size_t count, void* f) 
Arguments: br_size t count 
Number of bytes to advance. 
void * f 
Valid file handle - as returned by CBFnFileOpenRead (),., and 
CBFnFileOpenWrite () 3.0. 


Preconditions: | BRender has completed initialisation. BRender is the only direct caller of this 
function. 


Effects: | Advance file position by count bytes. 


Example: See stdfile.c for examples of filing system functions. 
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brfile attributes cbfn 


‘The Call-Back Function 


This type defines a filing system capabilities enquiry function, primarily intended for the 
attributes member of the br_filesystem,,, structure. 


The typedef 

(See brfile.h fora precise declaration) 

br_uint_32 brfile_attributes_cbfn (void) Get attributes of filing system 
Specification 


CBFnFileAttributes () 


Description: — An application defined call-back function returning capabilities of the filing 
system. 


Declaration: br_uint_32 BR_CALLBACK CBFnFileAttributes (void) 


Preconditions: | BRender has completed initialisation. BRender is the only direct caller of this 
function. 


Effects: | None. 
Result! br _uint_32 


The attributes of the filing system. Its capabilities as defined by a combination of 
the following flag values: 


Flag Attribute 

BR_FS_ATTR_READABLE Filing system can read files 
BR_FS_ATTR_WRITEABLE Filing system can write files 
BR_FS_ATTR_HAS_TEXT Filing system can interpret ASCII text files 
BR_FS_ATTR_HAS_BINARY Filing system can support binary files, i.e. 


maintains integrity of streams of any combination 
of bytes (8 bit). 
BR_FS_ATTR_HAS_ADVANCE_ |] Filing system can directly skip bytes 














Example: See stdfile.c for examples of filing system functions. 
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brfile close cbfn 


‘The Call-Back Function 


This type defines a file close function, primarily intended for the close member of the 
br_filesystem,,, structure. 


The typedef 


(See brfile.h fora precise declaration) 
void brfile_close_cbfn (void*) Close file 


Specification 


CBFnFileClose () 


Description: | An application defined call-back function closing a previously opened file. 
Declaration: void BR_CALLBACK CBFnFileClose(void* £) 
Arguments: void * £ 


Valid file handle - as returned by CBFnFileOpenRead (),., and 
CBFnFileOpenWrite () 3.0. 


Preconditions: | BRender has completed initialisation. BRender is the only direct caller of this 
function. 


Effects: — Close file. 


Example: See stdfile.c for examples of filing system functions. 
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brfile eof cbfn 


‘The Call-Back Function 


This type defines an end of file test function, primarily intended for the eof member of the 
br_filesystem,,, structure. 


The typedef 

(See brfile.h fora precise declaration) 

int brfile_eof_cbfn(const void *) Test for end of file 
Specification 


CBFnFileEOF () 


Description: | An application defined call-back function testing a file pointer for end of file. 
Declaration: int BR_CALLBACK CBFnFileEOF (const void* f) 


Arguments: const void * £ 


Valid file handle - as returned by CBFnFileOpenRead () ., and 
CBFnFileOpenWrite () 390. 


Preconditions: | BRender has completed initialisation. BRender is the only direct caller of this 
function. 


Effects: | None. 


Result: int 


Returns a non-zero value after the first read operation that attempts to read past the 
end of the file. It returns 0 if the current position is not end of file. 


Example: See stdfile.c for examples of filing system functions. 
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brfile_ getchr_cbfn 


‘The Call-Back Function 


This type defines a get character function, primarily intended for the getchr member of the 
br_filesystem,,, structure. 


The typedef 


(See brfile.h fora precise declaration) 


int 


brfile_getchr_cbfn(void *) Get character 


Specification 


CBFnFileGetChr () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 


Result: 


Example: 


382 


An application defined call-back function reading a character from a file. 
int BR_CALLBACK CBFnFileGetChr(void* f) 

void * £ 

Valid file handle - as returned by CBFnFileOpenRead () 33. 


BRender has completed initialisation. BRender is the only direct caller of this 
function. 


If the file position is at the end of the file, the file enters the end-of-file state, 
otherwise a character is read and the file position is advanced. 


int 
The character read from the file is returned (as though the character had been cast 


as (int) (unsigned char) ). Ifa character could not be read because the file 
position was at the end of the file, BR_EOF is returned. 


See stdfile.c for examples of filing system functions. 
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brfile getline_cbfn 


‘The Call-Back Function 


This type defines a get line function, primarily intended for the get line member of the 


br_filesystem,,, structure. 


The typedef 


(See brfile.h fora precise declaration) 


br_size t 


brfile_getline_cbfn(char*,br_size_t,void*) Getline 


Specification 


CBFnFileGetLine () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


Result: 


Example: 
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An application defined call-back function reading a line of text (excluding 
terminators) from a file. 


br_size_t BR_CALLBACK CBFnFileGetLine(char* buf, 
br_size_t buf_len, void* f) 


char * buf 

Buffer to hold text read. 

br_size_t buf_len 

Length of buffer (maximum number of characters to store - including ‘\0’). 
void * f 

Valid file handle - as returned by CBFnFileOpenRead () 39.. 


BRender has completed initialisation. BRender is the only direct caller of this 
function. 


En 


Read characters into supplied buffer until buf_len-1 characters have been read, 
end of line has been read, or end of file has been reached. If the last character read 


was ‘\n’ it is removed from the buffer. 


br_size t 


The number of characters stored in the buffer is returned. If at the end of file upon 


entry, zero will be returned. 


See stdfile.c for examples of filing system functions. 
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brfile open_read_cbfn 


‘The Call-Back Function 


This type defines a stream advance function, primarily intended for the open_read member of the 
br_filesystem,,, structure. 


The typedef 


(See brfile.h fora precise declaration) 


void* 


brfile_open_read_cbfn(const char*, br_size_t, 
br_mode_test_cbfn*, int*) 


Specification 


CBFnFileOpenRead () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


384 


Result: 


An application defined call-back function to open a file for read access. 


void* BR_CALLBACK CBFnFileOpenRead (const char* name, 
br_size_t n_magics, br_mode_test_cbfn* mode_test, 
int* mode_result) 


const char * name 

Name of file. 

br_size_t n_magics 

Number of characters required for mode_test to determine file type (less than 
or equal to BR_MAX_FILE_MAGICS). 

br_mode_test_cbfn mode_test 

Call-back function that can be used to determine file type given the first 
n_magics characters of a file. Will not be used if NULL. 

int * mode_result 

If this argument is non-NULL, the file type (if it could be determined) will be stored 
at the address pointed to. 


BRender has completed initialisation. BRender is the only direct caller of this 
function. 


Searches for a file called name, if no path 1s specified with the file, looks in the 
current directory, if not found tries, in order, the directories listed in 
BRENDER_PATH (if defined). Having found the file, use mode_test (if 
supplied) to find out if the file is text, binary or unknown. Store the result through 
mode_result (ifnon-NULL). Obtain a handle to the file. 


void * 


Return a file handle or NULL if the file could not be opened. 
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Remarks: ‘Text mode files are primarily used for debugging but can be useful to allow hand 
editing of input data. 


Example: See stdfile.c for examples of filing system functions. 
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brfile open_write_cbfn 


‘The Call-Back Function 


This type defines a function to open a file for writing, primarily intended for the open_write 
member of the br_filesystem,,, structure. 


The typedef 


(See brfile.h fora precise declaration) 


void * 


brfile_open_write_cbfn(const char*, int) Open file for writing 


Specification 


CBFnFileOpenWrite () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 
Result: 


Example: 


386 


Open a file for writing, overwriting any existing file of the same name. 


void* BR_CALLBACK CBnFileOpenWrite (const char* name, 
int mode) 


const char * name 

Name to open file as. 

int mode 

Mode in which to open file (BR_FS_MODE_TEXT or BR_FS_MODE_BINARY). 


BRender has completed initialisation. BRender is the only direct caller of this 
function. 


Overwrite or create file using specified name and mode. 
void * 
Return a file handle or NULL if the file could not be opened. 


See stdfile.c for examples of filing system functions. 
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brfile putchr_cbfn 


‘The Call-Back Function 


This type defines function to write a character to a file, primarily intended for the putchr member 
of the br_filesystem,,, structure. 


The typedef 


(See brfile.h fora precise declaration) 


void 


brfile_putchr_cbfn(int, void *) Write character to stream 


Specification 


CBFnFilePutChr () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 


Example: 


An application defined call-back function writing a single character to file. 
void BR_CALLBACK CBFnFilePutChr (int c, void* f) 

int c 

Character to write. 

void * £ 

Valid file handle - as returned by CBFnFileOpenWrite () 3... 


BRender has completed initialisation. BRender is the only direct caller of this 
function. 


Write the character to the file. 


See stdfile.c for examples of filing system functions. 
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brfile putline_cbfn 


The Call-Back Function 


This type defines a function to write a line of text to a file, primarily intended for the put line 
member of the br_filesystem,,, structure. 


The typedef 


(See brfile.h fora precise declaration) 


void 


brfile_putline_cbfn(const char*, void*) Write a line of text 


Specification 


CBFnFilePutLine () 


Description: 


Declaration: 


Arguments: 


Preconditions: 


Effects: 


Example: 


388 


An application defined call-back function writing a line of text toa file, followed by 
writing the new-line character (‘\n’). 


void BR_CALLBACK CBFnFilePutLine (const char* buf, void* f£) 
const char * buf 

Pointer to zero terminated string containing line of text to be written. 

void * £ 

Valid file handle - as returned by CBFnFileOpenWrite () 3.0. 


BRender has completed initialisation. BRender is the only direct caller of this 
function. 


Write the string to the file. Write the new-line character to the file (‘\n’). 


See stdfile.c for examples of filing system functions. 
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brfile read cbfn 


‘The Call-Back Function 


This type defines a function to read a block from a file, primarily intended for the read member of 
the br_filesystem,,, structure. 


The typedef 

(See brfile.h fora precise declaration) 

br_size t brfile_read_cbfn (void*,br_size_t, unsigned, void*) Read block 
Specification 


CBFnFileRead () 


Description: — An application defined call-back function reading a block from a file. 


Declaration: br_size_t BR_CALLBACK CBFnFileRead(void* buf, br_size _t size, 
unsigned int nelems, void* f) 


Arguments: void * buf 
Buffer to receive block. 
br_size_ t size 
Size of each element in block. 
unsigned int nelems 
Maximum number of elements to read. 
void * f 
Valid file handle - as returned by CBFnFileOpenRead () ,... 


Preconditions: | BRender has completed initialisation. BRender is the only direct caller of this 
function. 


Effects: | Read uptonelems elements of size bytes from the file £ and store them in 
buf. 


Result: br size_t 


Return the number of complete elements read, which may be less thannelems if 
the end of file is encountered before all the elements could be read. 


Example: See stdfile.c for examples of filing system functions. 
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brfile write cbfn 


‘The Call-Back Function 


Th 


is type defines a function to write a block to a file, primarily intended for the write member of 


the br_filesystem,,, structure. 


The typedef 


(See brfile.h fora precise declaration) 
br_size t brfile_write_cbfn(const void*,br_size_t,unsigned, void*) Write 


block 


Specification 


CBFnFileWrite () 


Description: — An application defined call-back function writing a block to a file. 


Declaration: br_ size_t BR_CALLBACK CBFnFileWrite(const void* buf, 
br_size_t size, unsigned int nelems, void* f) 


Arguments: const void * buf 
Buffer containing block to be written. 
br_size_t size 
Size of each element in block. 
unsigned int nelems 
Maximum number of elements to write. 
void * f 
Valid file handle - as returned by CBFnFileOpenWrite () 3.0. 


Preconditions: | BRender has completed initialisation. BRender is the only direct caller of this 
function. 


Effects: Write up tonelems elements from buf to the file f. 
Result: br size t 


Return the number of complete elements written, which may be less than nelems 
if an error occurs (such as running out of file space). 


Example: See stdfile.c for examples of filing system functions. 
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brmem allocate _cbfn 


‘The Call-Back Function 


This type defines a memory allocation function, primarily intended for the allocate member of the 
br_allocator,,, structure. 





The typedef 

(See brmem.h fora precise declaration) 

void * brmem_allocate_cbfn(br_size_t,br_uint_§8) Allocator 
Specification 


CBFnMemAllocate () 


Description: An application defined call-back function returning a pointer to newly allocated 
memory of specified size and type. 

Declaration: void* BR_CALLBACK CBFnMemAllocate(br_ size t size, 
br_uint_8 type) 

Arguments: br_ size t size 
Size in bytes of memory block required. More bytes may be allocated, but the caller 
will only use the first size bytes. Zero is a valid value. 
br_uint_8 type 
Class (type ID) of memory required. Although it is possible for the class to be 
ignored, it may be used for diagnostic purposes, or could be used to provide a more 
efficient allocation scheme. See Memory Classes for a description of possible 
values. 

Preconditions: The diagnostic handler has been setup (BrDiagHandlerSet () ,,,). BRender has 
not necessarily completed initialisation. This may not be the first allocator to have 
been called. BRender 1s the only direct caller of this function. 

Effects: | Obtain a fixed, contiguous, persistent, readable, writable, non-volatile area of 
memory of at least the size specified (even if zero), that will remain so until a 
corresponding call of CBFnMemF ree () ,., has occurred. 

Result: void * 


The address of a block of memory of the required size. If the request cannot be 
satisfied, return NULL. 


No assumption can be made concerning any relation between the address returned 
by this call and any previous or subsequent call. 
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Remarks: — Although BRender’s default diagnostic handling system does not use the memory 
handler, if you supply a diagnostic handler that does, you may have to handle 
memory allocation failures directly. 


The value returned by CBFnMemInquire () 3), does not guarantee the 
subsequent success or failure of CBFnMemA1 locate () 394. 

Example: See stdmem.c for examples of memory allocation functions. 

See Also: CBFnMemF ree () ,,, CBFnMemInquire () 49;. 
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brmem free cbfn 


‘The Call-Back Function 


This type defines a memory deallocation function, primarily intended for the free member of the 
br_allocator,,, structure. 


The typedef 

(See brmem.h fora precise declaration) 

void brmem_free_cbfn (void *) Deallocator 
Specification 


CBF nMenF ree () 


Description: | An application defined call-back function that will reclaim memory previously 
allocated by CBFnMemAllocate () 34. 


Declaration: void BR_CALLBACK CBFnMemFree(void* block) 
Arguments: void * block 
Address of memory no longer required, previously returned by the corresponding 


CBFnMemA1l locate () 4, (with no intervening CBFnMemF ree () 39,). NULL is 
ignored. 

Preconditions: "The diagnostic handler has been setup (BrDiagHandlerSet () ,,,). BRender has 
not necessarily completed initialisation. Other allocation handlers may have 
already been used. BRender is the only direct caller of this function. The 
application has disposed of all references to the memory (obtained using the 
supplied address). 


Effects: | Release supplied memory (presumably making it available for re-use). 
If the supplied address is invalid (not recognised as previously allocated by the 
corresponding CBFnMemA1l locate () 3,), consider this a failure condition and 


handle appropriately. Note that the BRender diagnostic handling system may not 
be available, or even capable of handling this condition. 


Remarks: The memory freed will not necessarily increase the value returned by 
CBFnMemInquire () ,,, though it is of course a hopeful effect. 
The application should immediately set to NULL all pointers referencing the 
memory freed, (at least in a debug version). 
Example: See stdmem.c for examples of memory deallocation functions. 
See Also: CBFnMemAllocate () »,, CBFnMemInquire () 5. 
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brmem_ingquire_cbfn 


‘The Call-Back Function 


This type defines a memory inquiry function, primarily intended for the inquire member of the 
br_allocator,,, structure. 


The typedef 


(See brmem.h for precise declaration) 


br_size t 


brmem_inquire_cbfn(br_uint_8) Inquiry function 





Specification 


CBFnMemInquire () 


Description: 
Declaration: 


Arguments: 


Preconditions: 


Effects: 


Result: 


Remarks: 


394 


An application defined call-back function providing details of memory availability. 
br_size_t BR_CALLBACK CBFnMemInquire(br_uint_8 type) 
br_uint_8 type 

Class of memory for which information is required. See Memory Classes for a 
description of possible values. 


The diagnostic handler has been setup (BrDiagHandlerSet () ,,,). BRender has 
not necessarily completed initialisation. Other allocation handlers may have 
already been used. BRender is the only direct caller of this function. 

Calculate an estimate of available memory for a particular memory class. This 
should be the total number of free bytes, irrespective of fragmentation or likely 
block-header overheads. If the class memory space would be extended, then the 
estimate should be of the potential maximum size available. 


br_size_t 
The total number of bytes remaining unallocated in the specified memory class. 


This function is only intended to provide an estimate of available memory. It does 
not guarantee that a particular allocation would succeed (or fail). However, it could 
be used as an indication of likely success or failure. 


There is no relation defined between the values returned for each class. In some 
allocation schemes, each class may havea separate and fixed amount of memory set 
aside, whereas in other schemes, all classes may be sharing all memory. 


There is no relation defined between the true amount of memory (whether virtual 
or physical) in a system, and the value returned by this function. 
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Example: See stdmem.c for examples of memory inquiry functions. 
See Also: CBFnMemAllocate () »,, CBFnMemF ree () 3. 
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BrMatrix34Copy4() ......-..-2---- 207 BrMatrix4Copy34() ....-..-..-e eee 224 
BrMatrix34Identity().........06. 209 BrMatrix4Determinant().......... 222 
BrMatrix34Inverse() ........0000. 190 BrMatrix4Identity().............. 225 
BrMatrix34LPInverse()........... 191 BrMatrix4Inverse() ......ccceeeees 216 
BrMatrix34LPNormalise()........ 208 BrMatrix 4M dC) ise fetes ees eee sedan d 216 
BeMabet eS 4Muse() wisn 2a8 aie Redae we okie 189 BrMatrix4Perspective().......... 226 
BrM@trtx34POSt-()ienckedkdsao eae ack 200 BrMatrix4Pre34() ..ccece ccc c ee ceee 220 
BrMatrix34PostRotate() ......... 203 BrMatrix4PreTransform()......... 221 
BrMatrix34PostRotateX() ........ 203 BrMatrix4Scale() .....c cece cece eee 225 
BrMatrix34PostRotateY() ........ 203 BrMatrix4TApply() .....seeeee eee 219 
BrMatrix34PostRotateZ()........ 204 BrMatrix4TApplyP()..........----- 219 
BrMatrix34PostScale()........... 201 BrMatrix4TApplyV() ........-.--0-- 220 
BrMatrix34PostShearX() ......... 201 BrMatrix4ToEuler() ........... cee 222 
BrMatrix34PostShearY() ......... 202 BrMatrix4ToQuat() .........e eee eee 223 
BrMatrix34PostShearZ() ......... 202 BrMemAllocate()...... ccc ccc cece eens 55 
BrMatrix34PostTransform()...... 204 BrMeMmCal LOG ()* :avewiccdewosedes Had eee 55 
BrMatrix34PostTranslate()...... 200 BrMemFree ()... cece cece cece e cee eeees 56 
BrMatrix34Pre() .... cece eee eee ee 195 BrMemInquire() ....c ec ec ec ee cence eees 55 
BrMatrix34PreRotate()........... 198 BEMemSt2Dup.()\ tai ac ghee es td aes 56 
BrMatrix34PreRotateX() ......... 198 BYMOde@lAdG () cei cceccdaawed es Badin’ 235 
BrMatrix34PreRotateY() ......... 199 BrModelAddMany() .......eceeeeeeee 236 
BrMatrix34PreRotateZ() ......... 199 BrModelAllocate() .........c. cc eee 239 
BrMatrix34PreScale()............ 196 BrModelApplyMap() ..........e ee eee 233 
BrMatrix34PreShearX()..........4. 196 BrModel Count () s.cecccaewse ea dadies 239 
BrMatrix34PreShearY()........... 197 BrModelEnum() ......cc cece eee wees 240 
BrMatrix34PreShearZ()........... 197 BrModelFileCount ()............006 243 
BrMatrix34PreTransform()....... 199 BrModelPind () cscecced see cecebedene 240 
BrMatrix34PreTranslate()....... 195 BrModelFindFailedLoad()......... 242 
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BrModelFindHook() ..........0c eee 241 BrPOOLFree() ... cece cece cece ee eees 301 
BrModelFindMany() .........eee eee 241 BrQuatInvert ()...... cece cece ee cees 313 
BrModelFitMap()......ce cece cee eeee 233 BEOUGEMUL ()0 4 os 6.08 o5 258 Vee 312 
BrModelFree() ..... cece ccc ccc cece 239 BrQuatNormalise() ............008- 315 
BrModelLoad () wi iiv eed ee isi eae es 243 BrQuat Slerp:()issisn.t eo wee eee oe 313 
BrModelLoadMany() .........eee eens 244 BrQuatToEuler() ........ceceeeeeee 314 
BrEModelTPiCK2D () ecb srieadieti ed's 231 BrQuatToMatrix34().........eeaeee 314 
BrModelRemove()... ccc cece cee eceees 237 BrQuatToMatrix4() ........ce eee 315 
BrModelRemoveMany().........eee0- 238 BERGESAAGi().s5sie4e oi eet wietde ek ke wets 49 
BrModelSave() .....cccceecceeaceees 245 BrResAllocate() ......cc cece ee eeees 48 
BrModelSaveMany() .....ceeeeeceeee 246 BrResChildEnum() ..........cceeeees 50 
BrModelUpdate()... cece ee eee eee 237 BERESClTASSI(): tegen eee eae Ste 49 
BrOnScreenCheck () ......c.cceceees 250 BrResClassAddi(): s:feuiseciadecea aoe 324 
BrOriginToScreenXY ()........ ee eee 251 BrResClassAddMany()..........000- 325 
BrOriginToScreenXYZO() .......... 252 BrResClassCount () ......0...cc eee 328 
BrPixelmapAllocate()............. 284 BrResClassEnum() .......ceee ee eeee 329 
BrPixelmapAllocateSub()......... 285 BrResClassPindit:) +0422 f508 knee 327 
BrPixelmapChannels()..........44- 287 BrResClassFindHook() .........05- 328 
BrPixelmapClone() .......ce eee eeee 286 BrResClassFindMany() ........e00- 327 
BrPixelmapCopy().....ceceeececeees 279 BrResClassRemove().......eece eens 325 
BrPixelmapDirtyRectangleCopy() .42 BrResClassRemoveMany().........-- 325 
BrPixelmapDirtyRectangleFill() .42 BrResFr6e ()* Jota chic eeann seiko a ete 51 
BrPixelmapDoubleBuffer()......... 44 BrReESRemove () ...ccccccceccccecceees 51 
BrPixelmapFileCount() ........... 294 BERESSA ZC) 2h kl ee he Weeks YOR 50 
BrPixelmapFill ()...........ceeeeee 275 BrResStrDup() i sussac vga tate ee es 49 
BrPixelmapFree ()..... cece cece ee eee 286 BrSceneModelLight ()..........606. 234 
BrPixelmapLine ().......ce cece ences 275 BrScenePick2D() .ssccsaeveccdecaccs 84 
BrPixelmapLoad ().......... cee eees 294 BrSCenePECK3D'(): vant dsradind eae ees 83 
BrPixelmapLoadMany()............- 294 BrScreenXYZToCamera() ............ 24 
BrPixelmapMatch() ............000- 285 BrScreenZToCamera().........2eeeee 24 
BrPixelmapPixelGet ().........005. 276 BETADLSAG ()) tn.tincOd ogdetiea neeteek 282 
BrPixelmapPixelSet ().........000. 276 BrTableAddMany() .......eececeeees 282 
BrPixelmapPixelSize() ........... 287 BETaAbLEeCOuNt. (iv aia.cdedeatioe sealed es 290 
BrPixelmapRectangleCopy() ...... 280 BreTablernum() ppc i4 see gated a eae 291 
BrPixelmapRectangleFill() ...... 275 BETADLEP ING ()issis eeti cations oat 291 
BrPixelmapSave ()...... cee ee eee eens 296 BrTableFindFailedLoad()......... 293 
BrPixelmapSaveMany()............- 297 BrTableFindHook ()..........20008. 292 
BrPixelmapText ()..... cece cece eeces 276 BrTableFindMany () ......eeceeeeeee 292 
BrPixelmapTextF() .....ce cece ee eee 277 BrTableRemove() wc... eee e ee ee eee 283 
BrPixelmapTextHeight() .......... 279 BrTableRemoveMany ()...........008- 283 
BrPixelmapTextWidth() ........... 278 BrTableUpdate() .......c ee cee cece 283 
BrPointToScreenXY()..... cee eee eee 251 BrTransformToMatrix34()......... 342 
BrPointToScreenXYMany()......... 251 BrTransformToTransform() ....... 342 
BrPointToScreenXYZO() ........... 253 BrVector2Accumulate()........... 349 
BrPointToScreenXYZOMany() ...... 253 BEVECEOFZAdG 0) acaw ea ware aiecsoad aoeares 349 
BrPoolAllocate().....c.cc cece t eae 300 BrVector2Copy () ..cccccccececccace 352 
BrPoolBlockAllocate() ........... 299 BrVECEORZDOE() aan G eee ast ere stein taeeates 351 
BrPoolBlockFree() 2... cece cece eee 299 BrVector2InvScale()...........05. 350 
BrPoolEmpty:()) insiwtel.awetetawiaun 300 BrVector2Length() .............08- 351 
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BrVector2LengthSquared()....... 351 BrZsOrderTablePrimitivelInsert () 262 
BrVector2Negate() ....... eee ee eee 348 BrZsPrimitiveBucketSelect()....309 
BrVector2Normalise()............ 352 BrZsPrimitiveCallbackSet()...... 39 
BrVeEctor2Scale() .i.cccccccaccvaces 350 BrZsRenderBoundsCallbackSet() ..39 
BrVector2Set () ....cceece ccc cceeess 353 BrZsSceneRender () .... ccc ec eee eeeee 35 
BrVector2SetFloat () .....cceceees 353 BrZsSceneRenderAdd() ......... eee 37 
BrVector2SetInt:() sss6eb veccswesa’ 354 BrZsSceneRenderBegin() ........... 36 
BEVeCHOF2ZSUD (CO) eis oi eA aes 349 BrZsSceneRenderEnd() .........000- 38 
BrVector3Accumulate()........... 356 BrZsScreenZToDepth() ........0008. 33 
BrVect or3Add () weve. cence eee seeds 356 CBFnActorEnum()..cessess4.eede gas 99 
BEVECt OES CODY. ()) sevSaleerehev ere os 361 CBFnDiagFailure() .............0.. 114 
BrVector3Crossi() i. duudaskresnnett 358 CBFnDiagWarning() .........ee eens 115 
BrVeCctor3 DO: (\oawt iehids Soha 358 CBFnFileAdvance() .......ce cence eee 369 
BrVector3InvScale() .........006. 358 CBFnFileAttributes() ............ 370 
BrVector3Length() ............ eee 359 CBFNFALeEClOSE () a ais noe hs BU tS 371 
BrVector3LengthSquared()....... 359 CBPNF 1 LEROF ) 34 a itacs icckil ee saas 372 
BrVector3Negate() ....... eee ee eee 356 CBFnFileGetChr() ........cce ee eeee 373 
BrVector3Normalise()............ 360 CBFnFileGetLine() ...........0005e 374 
BrVector3NormaliseLP() ......... 360 CBFnFileOpenRead()...........00ee 375 
BrVector3NormaliseQuick()...... 360 CBFnFileOpenWrite()............4. 377 
BrVector3Scale()..... cece eee ween 357 CBFNE?LePUECHE ()i ies es cure etna 378 
BrVector3Set () ..... cece cece ee eees 362 CBFnFilePutLine() ............0055 379 
BrVector3SetFloat () .....cceceees 362 CBFnFileRead () ....... cece cece eeees 380 
BrVector3SetInt() ...........00e. 363 CBFNFileWrite()..... ccc eee e eee eee 381 
BrVeCct or 3Sub() aienecatoa ohedeas 357 CBFNMapEnum () genaveeddedeesaeeaee 150 
BEVeECtOP4 Copy () i.anesle sins aga eee oa 365 CBFNMapF ings) scan iia teeaa ee gale 151 
BEVeECEOPADOE() atest eels sad ee eels 364 CBFnMaterialEnum() ..........00005 170 
BrWriteModeSet ()...... cece cee e wees 64 CBFnMaterialFind() ...........60.. 171 
BEZDBE GTC ae os. the aoe led saa eee lad 28 CBFnMemAllocate() ........e cece eee 382 
BrZbDepthToScreenZ()..........05. 30 CBFnMemFree () ..... cece eee cece ee nee 384 
BEZbDENGIC) “ac sanata lie hei teaedttaealas 40 CBFnMemInquire() ......ce cece eeeee 385 
BrZbModelRender() ......eceeeeeee 249 CBFnModelCustom() ......ece cece eee 247 
BrZbRenderBoundsCallbackSet().. 38 CBFnModelEnum()........c cece eee ee 255 
BrZbSceneRender () ......eceeeccees 34 CBFnNModelFind().....ccccccccacceen 256 
BrZbSceneRenderAdd()........0000- 36 CBFnModelPick2D() ......... cece eee 257 
BrZbSceneRenderBegin() .......... 35 CBFnModeTest ()....ccece cece ceceees 227 
BrZbSceneRenderEnd().........0085 37 CBFNPUCle2 DA). coh ceca ee Pa eueceeg Backes 267 
BrZbScreenZToDepth().........00ee 31 CBPAPYVCOKSD.). sic aceatene th autos tates 269 
BrZsActorOrderTableGet()........ 88 CBFNPrimitive()........ cece cece eee 307 
BrZsActorOrderTableSet()........ 87 CBFnRenderBounds () .......eeeeeeee 317 
BEASBeEG ini () Sessseted aiccccost gps Maotats eet 28 CBFnResClassEnum() .........00000e 320 
BrZsDepthToScreenZ()..........0.. 32 CBFnResClassFind() ..........000ee 321 
BEASENG:C). 40 stieetaeac0bd sareedlawars ees 40 CBFnNRESEnum() ......cccc cece caceeen 322 
BrZsModelRender() .......eeeeeeee 250 CBFnResourceFree() .... eee cece eee 330 
BrZsOrderTableAllocate()....... 265 CBFnTableEnum().........cccceeeees 336 
BrZsOrderTableClear()........... 264 CBENTaAbITE PAN A(:) Santee gece es Hades 337 
BrZsOrderTableFree()............ 266 

BrZsOrderTablePrimaryDisable() 264 

BrZsOrderTablePrimaryEnable(). 263 
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O-9 
2D 
Affine matrix 172 
Model pick 231 
Pick call-back 267 
32 bit 
Colour representation 112 
3D 
Affine matrix 188, 215 
Manipulator 69 
Pick call-back 269 
3D Studio 
Importing 244 


A 
Absolute 
Fixed 130 
Scalar 332 
‘Access & Maintenance’ 
Structure heading — see Heading 
Accumulate 
Vector 356 
Accumulating 
Transforms 82, 83 
Actor 12 
2D pick 84 
Add 80 
Allocate 89 
Bounding box 82, 106 
Bounds 20, 77, 82 
Bounds correct 20, 77 
Camera 18, 77 
Change parent 81 
Children 75 
Clip plane 21, 77, 86—7 
Co-ordinate space 22 
Count in file 94 
Depth 76 
Disable 
Clip plane 87 
Light 86 
Dummy 13, 77 
Enable 
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Clip plane 86 
Light 85 
Enumerate 91, 99 
Environment material 153 
Free 90 
Function 76, 85 
Functions 13 
Hierarchical relationship 12, 75, 80 
Identifier 80 
Light 17, 77, 85-6 
Load 95, 97 
Material 78 
Model 14, 77-8 
Move 81 
Next sibling 75 
None 13, 77 
Parent 75 
Positional relationship 12, 76, 82 
Previous sibling 75 
Reference 13, 77 
Relink 81 
Remove 81 
Rendering style 79 
Root 13 
Save 94, 96 
Search 92 
Set environment 85 
Structure 74 
to Actor 82 
to Screen matrix 83 
Transform 76, 82 
Type 76—7 
Type data 77 
User data 80 
Add 
Actor 80 
Child actor 80 
Material 159 
Model to registry 235—6 
Resource 49 
Resource class 324—5 
Scalar 331 
Scene to rendering 36, 37 
Shade table to registry 282 
‘Texture map to registry 280-1 
Vector 349, 356 
Adjoint 
Matrix 221 


395 


General Index 


Advance 

File 62 

Call-back 128, 369 

Affine 

2D matrix 172 

3D matrix 188, 215 
Allocate 

Actor 89 

Material 161 

Memory 55 

Call-back 100, 382 

Model 239 

Order table 265 

Pixel map 284 

Pool 300 

Pool block 299 

Resource 48 
Allocator 

Identifier 101 

Set 101 

Structure 100 
Alpha 72 

Channel 287 

Colour component 113 
Always visible 

Texture 153 
Ambient 

Lighting 15, 155 
Angle 45 

Integral type 103 

of Spot light 147 

see Euler angle set 
Animating 

Textures 158 
Application memory class 55 
Apply 

Matrix to point 174, 176, 191—4, 217, 219 

Matrix to vector 175—6, 193—4, 218, 220 

Texture map 158, 233 
Arccosine 

Fixed 132 

Scalar 103 
Arcsine 

Fixed 132 

Scalar 103 
Arctangent 

Fixed 132 

Scalar 103 
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Arguments 

Function heading — see Heading 
Arithmetic 

Structure heading — see Heading 
ASCII 

Fonts 135 
Aspect 19 

Camera 109 
‘Copy/Assign’ 

Structure heading — see Heading 
Attach 

Actor 80 
Attenuation 

Light 146 
Attributes 

Filing system 57 

Call-back 126, 370 


B 
Back face culling 153 
Base 

Material index 156 
Begin 

Initialising the library 10 
Bilinear 

Interpolation of texture 153 
Binary 

Mode 57, 64, 227 
Bit map 

Font 136 
Blanking period 44 
Blend table 

Material 153, 157 

see Material, Shade table 
Block 

Pool block size 299 
Blue 

Colour component 113 
BMP 

Import 295 
Boolean 

Integral type 105 
Bounding box 

Actor 82, 106 

Check on screen 250 

Intersection 83 

Model 82, 106, 230 

Pick 83 

Rendering style 
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Edges 79 
Faces 79 
Points 79 
Bounding radius 230 
Bounds 
Actor 20, 77, 82 
of Order table 260 
Render call-back 38—9, 317 
Structure 106 
Bounds correct 
Actor 20, 77 
BRender 
Initialising the library 10 
Overview 2 
Termination 10—11 
What does it do? 3 
What is it? 2 
Why is it so good? 3 
Bucket 
of Order table 304 
Bucket sort 
Primitives 262 
see Z sort 
Buffer 
Double buffering 43 
see Pixel map 


C 
C Types 45 
Calculating 
Actor bounding box 82 
Call-back 
2D pick 267 
3D pick 269 
Custom model 229, 247 
Enumerate 
Actor 99 
Resource 322 
Resource class 320 
Texture map 150 
Failure diagnostic 114, 116 
File 
Advance 128, 369 
Close 127, 371 
End of file 127, 372 
Get character 127, 373 
Get line 128, 374 
Open 127, 375, 377 
Put character 127, 378 
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Put line 128, 379 
Read block 127, 380 
Write block 127, 381 
Filing system 
Attributes 126, 370 
Find 
Resource class 321 
Texture map 151 
Inquire 
Memory 385 
Material 
Enumerate 170 
Find 171 
Memory 
Allocate 100, 382 
Deallocate 100 
Free 384 
Inquire 100 
Mode test 227 
Model 
Enumerate 255 
Find 256 
Pick 257 
Primitive 39, 307 
Render bounds 38—9, 317 
Resource 
Free 324, 330 
Sample material find hook 165 
Set material find hook 164 
Set model find hook 241 
Set resource class find hook 328 
Set shade table find call-back 292 
Set texture map find hook 289 
Shade table 
Enumerate 336 
Find 337 
Warning diagnostic 115—16 


“The Call-back Function’ 


Structure heading — see Heading 


calloc() — see Memory allocate 
Camera 19 


Actor 18, 77 

Aspect 109 

Co-ordinate space 22 

Default 111 

Field of view 109 

Height of parallel projection 110 
Identifier 110 

Perspective matrix 226 
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General Index 


Structure 108 

Type 109 

User data 110 

Width of parallel projection 110 
Candlelight 

Point light 146 
Change 

Actor parent 81 
Channels 

of Pixel map 287 
Character 

Font 135 

Font bit maps 136 

Get from file 62 

Put to file 59 

Size 135 
Check 

Bounding box on screen 250 
Child 

Add actor 80 

Remove actor 81 
Children 

Actor 75 
Chunk 

Pool chunk size 299 
Class 

see Memory class 

see Resource class 
Clear 

Allocate memory 

Order table 264 
Clip plane 

Actor 21, 77, 86—7 

Disable 87 

Distance of hither 109 

Distance of yon 109 

Enable 86 
Clipping 

Outcodes 253 

see Clip plane 
Clone 

Pixel map 286 
Close 

File 63 

Call-back 127, 371 

CLUT 16 
Collision detection 83, 248 

see Pick 
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Colour 16 
Buffer — see Pixel map 
Integral type 112 
Light 146 
Look up table 16 
Material 156, 158 
Column 
Font spacing 136 
Comparison 
Structure heading — see Heading 
Conical 
Light 146 
Constant 
Light attenuation 147 
Constructing 
Actor 89 
Actor hierarchy 80—1 
Order table 265 
‘Construction & Destruction’ 
Structure heading — see Heading 
Conversion 
Structure heading — see Heading 
Converting 
Angle 104 
Colours 112 
Co-ordinates 23, 82—3, 226, 251—3 
Degrees 104 
Depth to view z ordinate 24 
Euler 
from Unit quaternion 314 
to Matrix 121-22 
to Unit quaternion 121 
Host to network word order 70 
Matrix 
from Unit quaternion 314-15 
Network to host word order 70 
Numbers 104 
Radians 104 
Scalar 104, 333 
Transform 
to Matrix 342 
Unit quaternion 
to Euler 314 
to Matrix 314-15 
View z ordinate to depth 24, 32 
Co-ordinate space 22 
Actor 22 
Camera 22 
Converting 82 
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Converting between 23 
from Actor to screen 83 
from Depth to camera 24 
from Model to screen 251-3 
Model 22 
Reference actor 13 
Sceen 23 
Screen 23, 24 
View 23 
World 22 
Co-ordinates 
Converting 23 
Generating for texture map 233 
Texture 233 
Coplanar faces 123 
‘Copy/Assign’ 
Structure heading — see Heading 
Copy 
Dirty rectangle 42 
Matrix 183, 207, 223-24 
Memory block 53 
Pixel map 44, 279 
Pixel map rectangle 280 
String 56 
Vector 352, 361, 365 
Cosine 
Angle 103 
Fixed 132 
Count 
Actors in file 94 
Materials in file 165 
Materials in registry 162 
Models in file 243 
Models in registry 239 
Pixel maps in file 294 
Resource class 328 
Shade tables in registry 290 
‘Texture maps in registry 287 
Create 
new resource class 325 
Creating 
Actor 89 
Depth buffer 286 
Off screen pixel maps 286 
Order table 265 
Resource class 324 
Cross 
Vector product 358 
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CRT fly back 44 
Culling 

Back face 153 
Custom 

Model 229, 247 

Model data 231 
Cylinder 

Texture map 233 


D 
Data 
Pixel map 273 
Daylight 
Ambient lighting 155 
Deallocate 
Material 162 
Memory 56 
Call-back 100, 384 
Model 239 
Pixel map 286 
Pool 301 
Decal 
Texture map 153 
Declaration 
Function heading — see Heading 
Default 
Actor camera 111 
Actor light 148 
Actor material 78 
Actor model 78 
Camera 111 
Diagnostic handler 10 
Filing System 10 
Filing system 10 
Light 148 
Material 78 
Memory allocator 10 
Model 78 
Order table 265 
Rendering style 79 
Defaults 
Creation of 10 
Depth 
Actor in Hierarchy 76 
Channel 287 
of Pixel map 287 
to View z ordinate 24 
Depth buffer 30, 272 
Initialising 30 
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Pixel map 286 
Description 
Function heading — see Heading 
Destroying 
Actor 90 
Order table 266 
‘Construction & Destruction’ 
Structure heading — see Heading 
Destructor 
of Resource 330 
Detach 
Actor 81 
Determinant 
Matrix 222 
Device 
Pixel map 274 
Diagnostic 65 
Default handler 10 
Failure call-back 114, 116 
Handler identifier 116 
Handler structure 116 
Set handler 10, 68, 117 
Warning call-back 115-16 
Difference 
of vectors 349, 357 
Diffuse 
Lighting contribution 155 
Lighting factor 16 
Dim 
Light attenuation 146 
Dimensions 
of Pixel map 273 
Direct 
Light 146 
Direct draw 72 
Dirty rectangle 
Copy 42 
Fill 42 
Tracking 41, 317 
Disable 
Clip plane 87 
Light 86 
Primary order table 264 
Disc 
Texture map 233 
Display 
Video buffer 43 
Dither 
Material 153 
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Divide 
Fixed 131 
Matrix 173-74, 190-1, 216 
Scalar 331-32 
Unit quaternion 313 
Vector by scalar 350, 358 
DOS 71 
Dot 
Vector product 351, 358, 364 
Double buffering 43 
Off screen pixel map 286 
Double sided 
Material 154 
DR DOS 71 
Draw 
Line in pixel map 275 
Dummy 
Actor 13, 77 
Duplicate 
String 49, 56 
Dynamic memory 53, 55 


E 
Edge 
Rendering style 79 
Effects 
Function heading — see Heading 
Empty pool 300 
Enable 
Clip plane 86 
Custom model call-back 229 
Light 85 
Primary order table 263 
Encoding 
of Font 136 
End 
BRender 11 
of File 58 
Call-back 127 
of file 63 
Call-back 372 
Rendering scene 37—8 
Z buffer 40 
Z sort 40 
Engine — see Rendering Engine 
Enumerate 
Actor 91 
Call-back 99 
Material 162 
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Call-back 170 
Model 240 
Call-back 255 
Resource 
Call-back 322 
Children (dependents) 50 
Resource class 329 
Call-back 320 
Shade table 291 
Call-back 336 
Texture map 288 
Call-back 150 
Environment 
Material 153 
Set actor 85 
Epsilon 
Scalar 333 
Euler angle set 46 
from Matrix 205, 222 
from Unit quaternion 314 
Order 120 
Structure 119 
to Matrix 121—22 
to Quaternion 121 
Transform 339, 340 
Example 
Function heading — see Heading 
Exponential 
Fixed 132 
‘Import & Export’ 
Structure heading — see Heading 


F 

Face 15 
Back face culling 153 
Colour 156 
Default material 78 
Flags 123 
Index 156 
Keep original 229 
Lighting 15 
Material 123, 152 
Matt 155 
Model 229 
Rendering style 79 
Shiny 155 
Smoothing 123 
Structure 123 
Texture co-ordinates 158 
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Vertex 366 
Vertices 123 
Failure 


Diagnostic call-back 114, 116 


Field of view 
of Camera 109 
File 
Advance 62 
Call-back 128, 369 
Close 63 
Call-back 127, 371 
End of file 58, 63 
Call-back 127, 372 
Get character 62 
Call-back 127, 373 
Get line 
Call-back 128, 374 
Get line of text 61 
Magics 60 
Material script 167, 168 
Mode test 
Call-back 227 
Open 57, 60 


Call-back 127, 375, 377 


Print formatted string 59 
Put character 59 
Call-back 127, 378 
Put line 59 
Call-back 128, 379 
Read block 61 
Call-back 127, 380 
Set write mode 64 
Write block 58 
Call-back 127, 381 
Write mode 227 
Filing system 57 
Attributes 57 
Call-back 126, 370 
Capabilities 57 
Default 10 
Identifier 128 
Initialising 10 
Set 10, 128 
Structure 126 
Fill 
Dirty rectangle 42 
Memory block 53 
Pixel map 275 
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Filter 
Texture 153 
Find 
Material 163 
Call-back 171 
Find failed 165 
Hook 164 
Model 240—41 
Call-back 256 
Sample hook 242 
Set hook 241 
Resource class 327 
Call-back 321 
Hook 328 
Shade table 291, 292 
Call-back 337 
Texture map 288—89 
Call-back 151 
Fit 
Map to model 233 
Fixed 
Fraction — see Fraction 
Integral type 130 
Pitch font 135 
Point number 331 
Floating 
point number 331 
Fluorescent 
Light 15, 155 
Fly back 44 
Font 
Height in pixel map 279 
Pitch 135 
Structure 135 
Width of string in pixel map 278 
Force front 
Material 154 
Format 
Print to pixel map 277 
Fraction 46 
Integral type 139 
Unsigned 345 
Vector 141—43 
Free 
Actor 90 
Material 162 
Memory 56 
Available 55 
Call-back 100, 384 
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Model 239 

Order table 266 

Pixel map 286 

Pool 301 

Pool block 298-99 

Resource 51 

Call-back 324, 330 

Front 

Material 154 
Fully lit 

Inner cone of spot light 147 
Function heading — see Heading 
Functions 33 

Actor 13 
Fundamental types 45 


G 
Games consoles 70 
General 
Lighting 15, 155 
Generating 
‘Texture co-ordinates 233 
Geometry 
Model 228, 229 
Origin offset 230 
Vertices 366 
Get 
Actor order table 88 
Character from file 62 
Line of text from file 61 
Pixel map pixel 276 
Get character 
Call-back 127, 373 
Get line 
Call-back 128, 374 
GIF 
Import 295 
Glyph 135, 137 
Gouraud 
Shading 153 
Green 
Colour component 112 


H 

Handler 
Diagnostic 68, 116 
Filing system 126, 128 
Memory allocation 56, 100 
Set diagnostic 117 
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Set memory allocator 101 
Heading 
Function 7 
Structure 7 
Height 
of Font characters 136 
of Font in pixel map 279 
of Pixel map 273 
Hidden surface removal 30 
Hierarchical relationship 12 
Actor 75, 80 
Highlight 16, 79 
Material specular lighting 156 
Sharpness 156 
Highlighting 79 
Hither 
Plane 109 
Homogenous 
2D matrix 172 
3D matrix 188 
Screen space 23 
Homogenous screen space — see Screen space 
Hook 
Material find 164 
Sample 165 
Model find 241 
Sample 242 
Resource class find 328 
Shade table find 292 
Sample 293 
‘Texture map find 289 
Sample 290 
Host to network 
Word order 70 


I 

Identifier 
Actor 80 
Allocator 101 
Camera 110 
Diagnostic handler 116 
Filing system 128 
Light 147 

Identity 
Matrix 185, 209, 225 
Transform 339 

IFF 
Import 296 
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General Index 


‘Import & Export’ 
Structure heading — see Heading 
Import 
3D Studio 244 
BMP files 295 
GIF files 295 
IFF file 296 
Neutral file format models 245 
TGA file 296 
Index 
Blend table 157 
Channel 287 
Material 156 
Shade table 156 
Vertex prelight 367 
Indexed 
Colour map 272 
Indirect 
Lighting 155 
Infinite 
Direct light 146 
Inheritance 14 
Initialisation 10 
Library 10 
Structure heading — see Heading 
Initialising 
Filing system 10 
Order table 264 
Pixel map 275 
Registry 10 
Renderer 27 
Resource classes 10 
Z buffer 30 
Z buffer renderer 28 
Z sort renderer 28 
Inner 
Cone of spot light 147 
Input Device Support 69 
Inquire 
Memory 55 
Call-back 100, 385 
Insert 
Primitive into order table 262 
Integer 
Integral type 144 
Unsigned 347 
“The Integral Type’ 
Structure heading — see Heading 
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General Index 


Intel 72 
Intensity 

Light 147 
Interior 

Face lighting 154 
Interpolation 

Spherical linear — see Unit quaternion 
Intersection 

Actor 83 

Object/object — see Pick 
Inverse 

Distance 332 

Matrix 173-74, 190-91, 216 

Pixel map 285 

Unit quaternion 313 


K 
Keep 


Original model data 229 


L 
Lamp 
Spot light 146 
Largest 
Representable scalar 333 
Length 
Fixed 131 
of Vector 332 
Vector 351, 359 
Length preserving 
Matrix 184 
Matrix inverse 174, 191 
Matrix normalise 208 
Matrix transform 339 
Level of detail 248 
Library 
Termination 10, 11 
‘Referencing & Lifetime’ 
Structure heading — see Heading 
Light 15, 18 
see Actor 
Actor 17, 77, 85—6 
Ambient 155 
Behaviour 146 
Colour 146 
Data structure 145 
Default 148 
Direct 146 
Disable 86 


404 


Enable 85 

Identifier 147 

Material 153 

Point 146 

Prelighting 234 

Spot 146 

Type 146 

User data 148 
Lightbulb 

Point light 146 
Line 

Draw in pixel map 275 

Primitive 305 
Linear 

Interpolated texture 153 

Light attenuation 147 
Load 

Actor 95, 97 

Material 166—68 

Model 243—45 

Pixel map 294—96 
Locate 

Actor file 94 

Material file 165 

Model file 243 

Pixel map file 294 
Logos 153 
Look up 

Transform 339, 340 
Low precision 

Normalise vector 360 
Luminous 

Light 15, 155 


M 
Machine word 
Ordering 70 
Macintosh 72 
Magics 60, 227 
Magnitude 
Vector 332, 351, 359 
‘Access & Maintenance’ 
Structure heading — see Heading 
malloc() — see Memory Allocate 
Manipulator 69 
Map — see Texture map 
Mask 
see Blend table 
Texture map 153 
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General Index 





Match Apply to point 191—94, 217, 219 
Pixel map 285 Apply to vector 193-94, 218, 220 
Material 15 Copy 183, 207, 223-24 
Add 159 Determinant 222 
Allocate 161 Divide 173-74, 190-91, 216 
Blend table 153, 157 from Euler 121—22 
Colour 158 from Transform 342 
Count 162 from Unit quaternion 314-15 
Count in file 165 Identity 185, 209, 225 
Default 78 Inverse 173—74, 190—91, 216 
Diffuse lighting 155 Multiply 173, 177-83, 189, 195-204, 216, 
Double sided 154 220-21 
Enumerate 162 Normalise 184, 208 
Call-back 170 Perspective 226 
Face 123 Rolling Ball 69 
Find 163 Rotate 187, 198-99, 203—4, 212-14 
Call-back 171 Scale 186, 196, 201, 210, 225 
Find failed load 165 Shear 187, 196-97, 201—2, 210-12 
Find hook 164 Structure 172, 188, 215 
Sample call-back 165 ‘Texture map transform 158 
Free 162 to Euler 205, 222 
Identifier 158 to Transform 206 
Index base 156 to Unit quaternion 205, 223 
Index range 156 Transform 199, 204, 221, 339, 341 
Lighting 15 Translate 185, 195, 200, 209 
Load 166—68 Transpose 193, 194, 219, 220 
Matt 155 Matt 
of Primitive 305 Material 155 
Prelighting 367 Maximum 
Remove 160-61 Vertex 230 
Save 168 Members 
Shade table 156 Structure heading — see Heading 
Shiny 155 Memory 
Specular lighting 156 Allocate 55 
Specular power 156 Call-back 100, 382 
Structure 152 Allocator 100 
Transform 158 Block copy 53 
‘Transparency 157 Block fill 53 
Transparent 158, 273 Class type 54 
Two sided 154 Deallocate 56 
Update 160 Free 56 
User data 159 Call-back 100, 384 
Matrix 46 Inquire 55 
2D Affine 172 Call-back 100, 385 
3D Manipulator 69 Management 53 
Actor to actor 82 Pools 56 
Actor to screen 83 Set allocator 101 
Adjoint 221 Memory allocation 
Apply 174-76 Default handler 10 


Copyright © 1996 Argonaut Technologies Limited 40 5 


General Index 








Handler 56 Lighting 15 
Pool 298 Load 243—45 
Set handler 10 Material 152 
Memory Class Morphing 248 
Application 55 Order table 87—8 
Inquire memory available 55 Performance 229 
Memory class 48 Pick 
Merge Call-back 257 
Order table 264 Pivot point 230 
Mesh Quick update 229 
Model 228 Remove from registry 237—38 
Minimum Render 249-50 
Vertex 230 Rendering style 79 
MIPS 72 Sample find hook 242 
Mode Save 245—46 
Binary 64 Set find hook 241 
Pick 231 Structure 228 
see Write mode 64 to Screen co-ordinate space 251 
Test call-back 227 Update 237 
Text 64 User data 231 
Model 14 Vertex 229, 366 
Actor 14, 77 Modified Extent — see Dirty rectangle 
Add to registry 235—36 tracking 
Allocate 239 Moon 
Apply texture map 233 Direct light 146 
Behaviour 229 Morphing 
Bounding box 82, 106, 230 Keep original model data 229 
Bounding radius 230 Model 248 
Co-ordinate space 22 Mouse 69 
Co-ordinates 366 Move 
Co-ordinates to screen space 251—53 Actor 81 
Count in file 243 MS DOS 71 
Count in registry 239 Multiply 
Custom call-back 229, 247 Fixed 130, 131 
Default 78 Fraction 139 
Default material 78 Matrix 173, 177-83, 189, 195-204, 216, 
Don’t Weld 229 220-21 
Enumerate 240 Scalar 331-32 
Call-back 255 Unit quaternion 312 
Face 229 Vector by scalar 350, 357 
Find 240—41 Vector cross product 358 
Call-back 256 Vector dot product 351, 358, 364 
Fit map 233 
Flags 229 N 
Free 239 Negate 
Generate prelit vertex values 234 Vector 348, 356 
Geometry 229, 366 Network to host 
Identifier 230 Word order 70 


Keep original 229 


406 Copyright © 1996 Argonaut Technologies Limited 


Neutral 

File format import 245 
Next 

Free block in pool 298 

Pool block on spike 302 
None 

Actor 13, 77 

Rendering style 79 

Texture map 233 
Normalise 

Matrix 184, 208 

Unit quaternion 315 

Vector 352, 360 
Null actor — see None actor 
Number 

of Materials 162 

of Model faces 230 

of Model vertices 229 

of Order table intervals 260 


O 
Object — see Actor 
Off screen 77 

Buffer, displaying 43 

Pixel map 286 

Swap 44 

Offset 

Model geometry origin 230 
On screen 77 

Check 250 
One 

Fixed 133 
Opacity 

see Blend table 
Open 

File 57, 60 

Call-back 127, 375, 377 

Operations 

Structure heading — see Heading 
Optimising 

Model rendering 229 
Order table 31 

Allocate 265 

Bucket 304 

Clear 264 

Default 265 

Disable primary 264 

Enable primary 263 

Flags 261 
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General Index 


Free 266 

Get actor 88 

Insert primitive 262 

Merge 264 

Primary 259 

Primitive 304 

Set actor 87 

Size 260 

Structure 259 

Type 261 

Visits 262 

Z range 260 

Z sort position 260 
Ordering 

Machine word 70 
Origin 

of pixel map 273 
Original 

Keep model data 229 
Other Actors 20 
Out codes 253 
Outer 

Cone of spot light 147 


P 
Palette 16 
Pixel map 274 
Parallel 
Camera 109 
Light 146 
Parent 
Actor 75 
Partially lit 
Outer cone of spot light 147 
Pattern 
matching 92 
PC DOS 71 
Penumbra 
of spot light 147 
Perspective 
Camera 109 
Correct texture 153 
Matrix 226 
Phong 
Lighting 15 
Physical 
Pixel map width (row length) 274 
Screen space 23 
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General Index 


Pi 104 
Pick 44 
2D call-back 267 
2D scene 84 
3D call-back 269 
3D scene 83 
Model 231 
Call-back 257 
Pitch 
Font 135 
Pivot 
Point of model 230 
Pixel 
Get 276 
Set 276 
Pixel map 41 
Actor at pixel 84 
Allocate 284 
Channels 287 
Clearing 42 
Clone 286 
Copy 44, 279 
Copy rectangle 280 
Count in file 294 
Data 273—74 
Data structure 271 
Dimensions 273 
Dirty rectangle 
Copy 42 
Fill 42 
Double buffer 44 
Draw line 275 
Fill 275 
Flags 273 
Font 135-36 
Free 286 
Get pixel 276 
Identifier 274 
Load 294—96 
Match 285 
Material texture 158 
Operations 41 
Origin 273 
Palette 274 
Pixel get 276 
Pixel set 276 
Pixel size 287 
Rectangle fill 275 
Rendering to 41 
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Plan 


Rendering to video 43 
Save 296, 297 
Set pixel 276 
Suballocate 285 
Text 276, 277 
Text height 279 
Text width 278 
Type 272 

User data 274 
Using 41 

e 

Texture map 233 


Platform Specific 


Plot 


Structure heading — see Heading 


Point in pixel map 276 


Point 


Pool 


Apply matrix 174, 176, 191-94, 217, 219 


Light 146 
Primitive 305 
Rendering style 79 


see Memory 
Allocate 300 
Block 302 
Allocate 299 
Free 299 
Size 299 
Spike 302 
Chunk size 299 
Data structure 298 
Empty 300 
Free 301 
Memory class 299 


Positional relationship 12 


Actor 76, 82 


Power 


Fixed 132 
Scalar 332 
Specular lighting 156 


PowerPC 72 


Prec 


onditions 
Function heading — see Heading 


Prelit 
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Colours 367 

Generating prelit values 234 
Index 367 

Material 153 

Vertex 366 


Preprocessing 29 
Primary 
Order table 259, 263 
Disable 264 
Primitive 
Call-back 307 
Data structure 304 
Heap size 28 
Insert into order table 262 
Linked list 262 
Material 305 
Order table 259 
Set call-back 39 
Sorting 31 
Type 305 
Print 
Formatted string to file 59 
to Pixel map 277 
Projected 
Screen space 23 
Projected screen space — see Screen space 
Proportional 
Pitch font 135 
PSX 70 
Put character 59 
Call-back 127, 378 
Put line 59 
Call-back 128, 379 


Q 


Quadratic 
Light attenuation 147 
Quaternion — see Unit quaternion 


Quick 
Normalise vector 360 
Update 229 
R 
Radius 
Model 230 
Raise 
Fixed 132 
Scalar 332 
Range 


Material index 156 
Read block 61 

Call-back 127, 380 
Real 

Scalar number 331 
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General Index 


Reciprocal 
Fixed 132 
Fixed length 131 
Scalar 331 
Vector length 332 
Rectangle 
Copy 42, 280 
Fill 42, 275 
Red 
Colour component 112 
Reference 
Actor 13, 77 
‘Referencing & Lifetime’ 
Structure heading — see Heading 
Reflected light 15 
Registry 29 
Add material 159 
Add model 235, 236 
Add shade table 282 
Add texture map 280, 281 
Count materials 162 
Count models 239 
Count shade tables 290 
Count texture maps 287 
Enumerate material 162 
Enumerate model 240 
Enumerate shade table 291 
Enumerate texture maps 288 
Find model 240—41 
Find shade tables 291—92 
Find texture map 288—89 
Initialising 10 
Material find 163 
Model update 229 
Remove material 160—61 
Remove model 237—38 
Remove shade table 283 
Remove texture map 281—82 
Update material 160 
Update model 237 
Update shade table 283 
Update texture map 281 
Releasing 
Actor 90 
All memory 10 
Memory 56 
Order table 266 
Relink 
Actor 81 
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General Index 


Remarks 


Function heading — see Heading 


Remove 
Actor 81 
Child actor 81 
Material 160—61 
Model from registry 237—38 
Resource block 51 
Resource class 325 
Shade table from registry 283 
shade table from registry 283 


Texture map from registry 281—82 


Render 
Model 249, 250 
Render bounds 
Call-back 317 
Set call-back 38—9 
Renderer 
Initialising 27 
Terminating 40 
Z buffer 30 
Initialising 28 
Z sort 31 
Initialising 28 
Rendering 33 
Custom model 229, 247 
End 37-8 
Engine 26 
Pixel map to video 43 
Scene 34—7 
Style 79 
to Pixel map 41 
Resource 
Add 49 
Allocate 48 
Block class 49 
Block size 50 
Class type 54 
Duplicate string 49 
Enumerate 
Call-back 322 
Children (dependents) 50 
Free 51 
Call-back 324, 330 
Identifier 324 
Remove 51 
Resource class 48 
Add 324—25 
Count 328 
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Data structure 323 
Enumerate 329 
Call-back 320 
Find 327 
Call-back 321 
Find hook 328 
Initialising 10 
Remove 325 
Restarting 
BRender 10 
Result 


Function heading — see Heading 


Retaining 
Original vertices 229 
Retrace 44 
RGB 
Channel 287 
to Colour 112 
Rolling Ball 69 
Root 
Actor 13 
Fixed (square root) 132 
Scalar (square root) 332 
Rotate 


Matrix 180, 183, 187, 198-99, 203-4, 212— 


14 
Texture 158 
Row 
Font spacing 136 


S 
Sample 
Shade table find hook 293 
Texture map find hook 290 
Saturn 70 
Save 
Actor 94, 96 
Material 168 
Model 245—46 
Pixel map 296—97 
Scalar 45 
Fixed type 130 
Fraction 139 
Integral type 331 
Largest representable 333 
Smallest representable 333 
Unity — see Unity 
Unsigned fraction 345 
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Scale 
Matrix 178, 181, 186, 196, 201, 210, 225 
Texture 158 
Vector 350, 357-58 
Scene 
2D pick 84 
3D pick 83 
End rendering 37-8 
Model prelighting 234 
Rendering 34—7 
Screen 
Co-ordinate space 24 
from Actor co-ordinates 83 
space 23 
Script 
Material load 167, 168 
Searching 
for Actor 92 
for Material 162, 163 
for Model 240, 241, 256 
for Resource class 327, 328 
for Shade table 337 
‘See Also’ 
Function heading — see Heading 
Sega 70 
Selection 79 
Set 
Actor order table 87 
Diagnostic handler 10, 68, 117 
Environment actor 85 
Filing system 10 
Filing system handler 128 
Material find hook 164, 165 
Matrix 185-87, 209-14, 225 
Memory allocation handler 101 
Memory allocator 10 
Pixel map pixel 276 
Primitive call-back 39 
Render bounds call-back 38—9 
Resource class find call-back 328 
Shade table find hook 292 
‘Texture map find call-back 289 
Vector 353-54, 362—63 
Write mode 64 
Shade table 16 
Add to registry 282 
Count in registry 290 
Data structure 271 
Enumerate 291 
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General Index 


Call-back 336 
Find 291-92 
Call-back 337 
Find hook call-back 292 
Find hook sample 293 
Material 156 
Remove from registry 283 
Update in registry 283 
Shading 
Smooth 153 
Sharpness 
Highlight 156 
Shear 
Matrix 178-79, 182, 187, 196-97, 
201-2, 210-12 
Texture 158 
Shiny 
Material 155 
Sibling 
Actor 75 
Simple memory services 53 
Sine 
Angle 103 
Fixed 132 
Size 
Integral type 335 
of Order table 260 
of Pixels 287 
of Pool block 299 
Pool chunk 299 
Skeleton Application 26 
SLERP — see Unit quaternion 
Smallest 
Representable scalar 333 
Smooth 
Material 153 
Smoothing 
Face 123 
Sony 70 
Spacing 
Font 136 
Specification 
Structure heading — see Heading 
Specular 
Lighting contribution 156 
Lighting factor 16 
Power 156 
Sphere 
Texture map 233 
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General Index 


Spherical linear interpolation 

of Unit quaternion 313 
Spike 

Next pool block 302 
Spot 

Light 146-47 
Square 

Fixed 131 

Scalar 331 

Vector length 351, 359 
Square root 

Fixed 132 

Scalar 332 
Standard filing system services 57 
Stratum 

Depth 260 

Ordering 260 
String 

Duplicate 49, 56 
“The Structure’ 

Structure heading — see Heading 
Structure heading — see Heading 
Style 

Rendering 79 
Suballocate 

Pixel map 285 
Subtract 

Scalar 331 

Vector 349, 357 
Sum 

of Vectors 349, 356 
Sun 

Direct light 146 
Supplementary 

Structure heading — see Heading 
Surface — see Material 
Swapping 

Video buffers 43 
Switching 

Video buffers 43 
Synchronisation — See Video 


T 
Table — see Shade table 
‘Tangent 

Angle 103 
Terminating 

Renderer 40 
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Termination 
BRender 10-1 
Library 10-1 
Test 
for End of file 63 
Mode call-back 227 
On screen 250 
Text 
Font 135 
Get line 61 
Height in pixel map 279 
Mode 57, 64, 227 
Put line 59 
Width for font and pixel map 278 
Write string to pixel map 276-77 
Texture map 17 
Add to registry 280-81 
Apply 233 
Co-ordinates 366—67 
Count in registry 287 
Cylinder 233 
Data structure 271 
Decal 153 
Disc 233 
Dithering 153 
Enumerate 288 
Call-back 150 
Environment 153 
Find 288—89 
Call-back 151 
Find hook 289 
Fit to model 233 
Light 153 
Material 158 
None 233 
Plane 233 
Remove from registry 281—82 
Sample find hook call-back 290 
Sphere 233 
Transform 158, 172 
Transparency 158, 273 
Update 160, 281 
TGA 
Import 296 
“The Call-back Function’ 
Structure heading — see Heading 
“The Integral Type’ 
Structure heading — see Heading 
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“The Structure’ 
Structure heading — see Heading 
Transform 
Actor 76, 82 
Actor to actor 82 
Actor to screen 83 
Camera 226 
Data structure 338 
from Matrix 206 
Matrix 188, 199, 204, 221 
Texture map 158, 160, 172, 233 
to Matrix 342 
to Transform 342 
Type 339 
Translate 
Matrix 177, 181, 185, 195, 200, 209 
Texture 158 
Translation 
Transform 339 
‘Translucency 
see Blend table 
‘Transparent 
Material 157 
Texture 158, 273 
‘Transpose 
Matrix 176, 193-94, 219-20 
Triangle 
Primitive 305 
Trigonometry 103 
Fixed 132 
True colour 156 
Colour map 272 
Two 
Sided material 154 
Type 
Actor 76, 77 
Camera 109 
of Pixel map 272 


U 

Unit 
Vector 360 

Unit quaternion 47 
Data structure 311 
from Euler 121 
from Matrix 205, 223 
Inverse 313 
Multiply 312 
Normalise 315 
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General Index 


Spherical linear interpolation 313 
to Euler 314 
to Matrix 314-15 
Transform 339, 341 
nit vector 141—43, 352, 360 
nity 
Fixed 133 
Unknown 
Mode 227 
Unsigned fraction 
Integral type 345 
nsigned integer 
Integral type 347 
pdate 
Material 159-60 
Model 229, 237 
Model flags 229 
Shade table in registry 283 
Texture map 281 
Updating screen 43 
User defined 
Model member 231 
Model rendering 229 


aS 


io 





eG 


Vv 
Vector 46 
Add 349, 356 


Apply matrix 175-76, 193-94, 218, 220 


Copy 352, 361, 365 
Cross product 358 
Data structure 348, 355, 364 
Dot product 351, 358, 364 
Fractional 141—43 
Inverse scale 358 
Length 332, 351, 359 
Magnitude 332, 359 
Negate 348, 356 
Normalise 352, 360 
Scale 350, 357 
Set 353-54, 362—63 
Subtract 349, 357 

Vertex 14 
Colour 367 
Co-ordinates 366 
Data structure 366 
Don’t weld 229 
Generating prelit values 234 
Keep original 229 
Maximum 230 


General Index 


Model 229 

Offset 230 

Prelit index 367 

Specified in face 123 

‘Texture co-ordinates 233, 367 
Vertical retrace 44 
Video 

Blanking period 44 

Rendering pixel map to 43 
Video refresh — see Double buffering 
View 

Space 23 

Volume 24, 226 
Viewer — see Camera 
Viewing pyramid 

Angle 109 


WwW 
Warning 

Diagnostic call-back 115-16 
Width 

Font characters 135-36 

of Pixel map 273 

of String in font 278 
Wild cards 92 
Windows 71 
Wire frame 

Flags 123 

Rendering style 79 
Word 

Ordering 70 
World 

Co-ordinate space 22 
Write block 58 

Call-back 127, 381 
Write mode 64, 227 


Y 
Yon 
Plane 109 
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YUV 
Channel 287 
Zz 
Z 
Front material 154 
Z buffer 30 
Depth to camera z 24 
End 40 
Initialising 30 
Renderer 
Initialising 28 
see Pixel map 
Z sort 31 
End 40 
Get actor order table 88 
Insert primitive into order table 262 
Order table 259 
Renderer 
Initialising 28 
Set actor order table 87 
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Notes 


Notes 


Notes 


Notes 


BRender API Quick Reference 


Functions 


br_actor* BrActorAdd(br_actor* parent, br_actor* a) 82 

br_actor* BrActorAllocate(br_uint_8 actor_type, void* type data) 92 

br_uint_32 BrActorEnum(br_actor* parent, br_actor_enum_cbfn* callback, void* arg) 93 
br_uint_32 BrActorFileCount (const char* filename, br_uint_16* num) 97 

void BrActorFree(br_actor* a) 92 

br_actor* BrActorLoad(const char* filename) 98 

br_uint_32 BrActorLoadMany (const char* filename, br_actor** actors, br_uint_16 num) /00 
void BrActorRelink(br_actor* parent, br_actor* a) 83 

br_actor* BrActorRemove (br_actor* a) 83 

br_uint_32 BrActorSave(const char* filename, const br_actor* actor) 97 

br_uint_32 BrActorSaveMany(const char* filename, const br_actor* const * actors, br_uint_16 num) 99 
br_actor* BrActorSearch(br_actor* root, const char* pattern) 94 

br_uint_32 BrActorSearchMany (br_actor* root, const char* pattern, br_actor** actors, int max) 95 
br_uint_8 BrActorToActorMatrix34 (br_matrix34* m, const br_actor* a, const br_actor* b) 84 
br_bounds* BrActorToBounds (br_bounds* b, const br_actor* ap) 84 

void BrActorToScreenMatrix4 (br_matrix4* m, const br_actor* a, const br_actor* camera) 86 
const br_allocator* BrAllocatorSet (const br_allocator* newal) /03 

void BrBegin (void) /0 

void BrBlockCopy(void* dest_ptr, const void* src_ptr, int dwords) 54 

void BrBlockFill(void* dest_ptr, int value, int dwords) 54 

br_matrix34* BrBoundsToMatrix34 (br_matrix34* mat, const br_bounds* bounds) /09 

void BrClipPlaneDisable(br_actor* cp) 89 

void BrClipPlaneEnable(br_actor* cp) 89 

br_diaghandler* BrDiagHandlerSet (br_diaghandler* newdh) /19 

void BrEnd (void) // 

br_actor* BrEnvironmentSet (br_actor* a) 87 

br_matrix34* BrEulerToMatrix34 (br_matrix34* mat, const br_euler* euler) /23 
br_matrix4* BrEulerToMatrix4 (br_matrix4* mat, const br_euler* euler) /24 

br_quat* BrEulerToQuat (br_quat* q, br_euler* euler) /23 

void BrFileAdvance(long int count, void* £) 63 

br_uint_32 BrFileAttributes (void) 58 

void BrFileClose(void* f) 64 

int BrFileEof(const void* f) 64 

int BrFileGetChar(void* £) 63 

int BrFileGetLine(char* buf, br_size_t buf_len, void* f) 62 

void* BrFileOpenRead(const char* name, br_size_t n_magics, br_mode_test_cbfn* mode_test, int* mode_result) 6/ 
void* BrFileOpenWrite(const char* name, int mode) 58 

int BrFilePrintf(void* £, const char* fmt, ...) 60 

void BrFilePutChar(int c, void* f) 60 

void BrFilePutLine(const char* buf, void* f£) 60 

int BrFileRead(void* buf, int size, int n, void* f) 62 

const br_filesystem* BrFilesystemSet (const br_filesystem* newfs) /30 

int BrFileWrite(const void* buf, int size, int n, void* f) 59 

br_uint_32 BrFmtASCLoad(const char* name, br_model** mtable, br_uint_16 max_models) 248 
br_pixelmap* BrFmtBMPLoad(const char* name, br_uint_32 flags) 302 

br_pixelmap* BrFmtGIFLoad(const char* name, br_uint_32 flags) 302 

br_pixelmap* BrFmtIFFLoad(const char* name, br_uint_32 flags) 303 

br_model* BrFmtNFFLoad(const char* name) 249 

br_pixelmap* BrFmtTGALoad(const char* name, br_uint_32 flags) 303 

void BrLightDisable(br_actor* 1) 88 

void BrLightEnable(br_actor* 1) 88 

br_pixelmap* BrMapAdd(br_pixelmap* pixelmap) 287 

br_uint_32 BrMapAddMany (br_pixelmap* const* pixelmaps, int n) 287 

br_uint_32 BrMapCount (const char* pattern) 294 

br_uint_32 BrMapEnum(const char* pattern, br_map_enum_cbfn* callback, void* arg) 294 
br_pixelmap* BrMapFind(const char* pattern) 295 

br_pixelmap* BrMapFindFailedLoad(const char* name) 296 

br_map_find_cbfn* BrMapFindHook (br_map_find_cbfn* hook) 295 

br_uint_32 BrMapFindMany(const char* pattern, br_pixelmap** pixelmaps, int max) 295 
br_pixelmap* BrMapRemove (br_pixelmap* pixelmap) 288 
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BRender API Quick Reference 


br_uint_32 BrMapRemoveMany (br_pixelmap* const* pixelmaps, int n) 288 

void BrMapUpdate (br_pixelmap* pixelmap, br_uint_16 flags) 287 

void BrMatrix34RollingBall (br_matrix34* mat, int dx, int dy, int radius) 70 

void* BrMemAllocate(br_size_t size, br_uint_8 type) 56 

void* BrMemCalloc(int nelems, br_size_t size, br_uint_8 type) 56 

void BrMemFree(void* block) 57 

br_size_t BrMemInquire(br_uint_8 type) 56 

char* BrMemStrDup(const char* str) 57 

br_model* BrModelAdd(br_model* model) 240 

br_uint_32 BrModelAddMany (br_model* const* models, int n) 240 

br_model* BrModelAllocate(const char* name, int nvertices, int nfaces) 243 

void BrModelApplyMap (br_model* model, int map_type, const br_matrix34* xform) 237 

br_uint_32 BrModelCount (const char* pattern) 243 

br_uint_32 BrModelEnum(const char* pattern, br_model_enum_cbfn* callback, void* arg) 244 

br_uint_32 BrModelFileCount (const char* filename, br_uint_16* num) 247 

br_model* BrModelFind(const char* pattern) 244 

br_model* BrModelFindFailedLoad(const char* name) 246 

br_model_find_cbfn* BrModelFindHook (br_model_find_cbfn* hook) 245 

br_uint_32 BrModelFindMany (const char* pattern, br_model** models, int max) 245 

br_matrix34* BrModelFitMap (const br_model* model, int axis_0, int axis_1, br_matrix34* transform) 238 

void BrModelFree(br_model* m) 243 

br_model* BrModelLoad(const char* filename) 247 

br_uint_32 BrModelLoadMany (const char* filename, br_model** models, br_uint_16 num) 248 

int BrModelPick2D (br_model* model, const br_material* material, const br_vector3* ray pos, const br_vector3* ray dir, 
br_scalar t_near, br_scalar t_far, br_modelpick2d_cbfn* callback, void* arg) 235 

br_model* BrModelRemove (br_model* model) 24/ 

br_uint_32 BrModelRemoveMany (br_model* const* models, int n) 242 

br_uint_32 BrModelSave(const char* filename, const br_model* model) 249 

br_uint_32 BrModelSaveMany (const char* filename, const br_model* const* models, br_uint_16 num) 250 

void BrModelUpdate (br_model* model, br_uint_16 flags) 24] 

br_uint_8 BrOnScreenCheck (const br_bounds* bounds) 254 

br_uint_8 BrOriginToScreenxyY (br_vector2* screen) 255 

br_uint_32 BrOriginToScreenXYZO(br_vector3* screen) 256 

br_pixelmap* BrPixelmapAllocate(br_uint_8 type, br_uint_16 w, br_uint_16 h, void* pixels, int flags) 290 

br_pixelmap* BrPixelmapAllocateSub(br_pixelmap* pm, br_uint_16 x, br_uint_16 y, br_uint_16 w, br_uint_16 h) 29/ 

br_uint_16 BrPixelmapChannels (const br_pixelmap* pm) 293 

br_pixelmap* BrPixelmapClone (const br_pixelmap* src) 292 

void BrPixelmapCopy (br_pixelmap* dst, const br_pixelmap* src) 285 

void BrPixelmapDirtyRectangleCopy (br_pixelmap* dst,const br_pixelmap* src, br_int_16 x, br_int_16 y,br_uint_16 w, 
br_uint_16 h) 43 

void BrPixelmapDirtyRectangleFill (br_pixelmap* dst,br_int_16 x, br_int_16 y, br_uint_16 w, br_uint_16 h,br_uint_32 colour) 
43 

void BrPixelmapDoubleBuffer (br_pixelmap* dst, br_pixelmap* src) 45 

br_uint_32 BrPixelmapFileCount (const char* filename, br_uint_16* num) 30/ 

void BrPixelmapFill(br_pixelmap* dat, br_uint_32 colour) 28/ 

void BrPixelmapFree (br_pixelmap* pmap) 293 

void BrPixelmapLine (br_pixelmap* dst, br_int_16 x1, br_int_16 yl, br_int_16 x2, br_int_16 y2, br_uint_32 colour) 28/ 

br_pixelmap* BrPixelmapLoad(const char* filename) 30/ 

br_uint_32 BrPixelmapLoadMany (const char* filename, br_pixelmap** pixelmaps, br_uint_16 num) 30/ 

br_pixelmap* BrPixelmapMatch(const br_pixelmap* src, int match_type) 292 

br_uint_32 BrPixelmapPixelGet (const br_pixelmap* src, br_int_16 x, br_int_16 y) 282 

void BrPixelmapPixelSet (br_pixelmap* dst, br_int_16 x, br_int_16 y, br_uint_32 colour) 282 

br_uint_16 BrPixelmapPixelSize(const br_pixelmap* pm) 293 

void BrPixelmapRectangleCopy (br_pixelmap* dst, br_int_16 dx, br_int_16 dy, const br_pixelmap* src, br_int_16 sx, br_int_16 
sy, br_uint_16 w, br_uint_16 h) 286 

void BrPixelmapRectangleFill (br_pixelmap* dst, br_int_16 x, br_int_16 y, br_uint_16 w, br_uint_16 h, br_uint_32 colour) 28/ 

br_uint_32 BrPixelmapSave (const char* filename, const br_pixelmap* pixelmap) 304 

br_uint_32 BrPixelmapSaveMany (const char* filename, const br_pixelmap* const* pixelmaps, br_uint_16 num) 304 

void BrPixelmapText (br_pixelmap* dst, br_int_16 x, br_int_16 y, br_uint_32 colour, const br_font* font, const char* text) 
283 

void BrPixelmapTextF (br_pixelmap* dst, br_int_16 x, br_int_16 y, br_uint_32 colour, const br_font* font, const char* fmt, 
...) 283 

br_uint_16 BrPixelmapTextHeight (const br_pixelmap* dst, const br_font* font) 285 
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br_uint_16 BrPixelmapTextWidth (const br_pixelmap* dst, const br_font* font, const char* text) 284 

br_uint_8 BrPointToScreenxyY (br_vector2* screen, const br_vector3* point) 255 

void BrPointToScreenXYMany (br_vector2* screens, const br_vector3* points, br_uint_32 npoints) 256 

br_uint_32 BrPointToScreenxYZO (br_vector3* screen, const br_vector3* point) 257 

void BrPointToScreenXYZOMany (br_vector3* screens, br_uint_32* outcodes, const br_vector3* points, br_uint_32 npoints) 258 

br_pool* BrPoolAllocate(int block_size, int chunk_size, br_uint_8 mem_type) 308 

void* BrPoolBlockAllocate (br_pool* pool) 307 

void BrPoolBlockFree(br_pool* pool, void* b) 307 

void BrPoolEmpty (br_pool* pool) 308 

void BrPoolFree(br_pool* pool) 309 

br_quat* BrQuatInvert (br_quat* q, const br_quat* qq) 322 

br_quat* BrQuatMul (br_quat* q, const br_quat* 1, const br_quat* r) 32] 

br_quat* BrQuatNormalise(br_quat* q, const br_quat* qq) 325 

br_quat* BrQuatSlerp(br_quat* q, const br_quat* 1, const br_quat* r, br_scalar t, br_int_16 spins) 322 

br_euler* BrQuatToEuler(br_euler* euler, const br_quat* q) 323 

br_matrix34* BrQuatToMatrix34 (br_matrix34* mat, const br_quat* q) 323 

br_matrix4* BrQuatToMatrix4 (br_matrix4* mat, const br_quat* q) 324 

void* BrResAdd(void* vparent, void* vres) 50 

void* BrResAllocate(void* vparent, br_size_t size, int res_class) 49 

br_uint_32 BrResChildEnum(void* vres, br_resenum_cbfn* callback, void* arg) 5] 

br_uint_8 BrResClass(void* vres) 50 

br_resource_class* BrResClassAdd(br_resource_class* rclass) 335 

br_uint_32 BrResClassAddMany (br_resource_class* const* items, int n) 336 

br_uint_32 BrResClassCount (const char* pattern) 339 

br_uint_32 BrResClassEnum(char* pattern, br_resclass_enum_cbfn* callback, void* arg) 340 

br_resource_class* BrResClassFind(const char* pattern) 338 

br_resclass_find_cbfn* BrResClassFindHook (br_resclass_find_cbfn* hook) 339 

br_uint_32 BrResClassFindMany (const char* pattern, br_resource_class** items, int max) 338 

br_resource_class* BrResClassRemove (br_resource_class* rclass) 336 

br_uint_32 BrResClassRemoveMany (br_resource_class* const* items, int n) 336 

void BrResFree(void* vres) 52 

void* BrResRemove (void* vres) 52 

br_uint_32 BrResSize(void* vres) 5/ 

char* BrResStrDup(void* vparent, const char* str) 50 

void BrSceneModelLight (br_model* model, const br_material* default_material, const br_actor* root, const br_actor* a) 238 

int BrScenePick2D (br_actor* world, const br_actor* camera, const br_pixelmap* viewport, int pick_x, int pick_y, 
br_pick2d_cbfn* callback, void* arg) 86 

int BrScenePick3D(br_actor* world, const br_actor* reference, const br_bounds* bounds, br_pick3d_cbfn* callback, void* 
arg) 85 

void BrScreenXYZToCamera (br_vector3* point, const br_actor* camera, const br_pixelmap* screen_buffer, br_int_16 x, 
br_int_16 y, br_scalar zs) 25 

br_scalar BrScreenZToCamera(const br_actor* camera, br_scalar sz) 24 

br_pixelmap* BrTableAdd(br_pixelmap* pixelmap) 288 

br_uint_32 BrTableAddMany (br_pixelmap* const* pixelmaps, int n) 289 

br_uint_32 BrTableCount (const char* pattern) 297 

br_uint_32 BrTableEnum(const char* pattern, br_table_enum_cbfn* callback, void* arg) 297 

br_pixelmap* BrTableFind(const char* pattern) 298 

br_pixelmap* BrTableFindFailedLoad(const char* name) 299 

br_table_find_cbfn* BrTableFindHook (br_table_find_cbfn* hook) 299 

br_uint_32 BrTableFindMany (const char* pattern, br_pixelmap** pixelmaps, int max) 298 

br_pixelmap* BrTableRemove (br_pixelmap* pixelmap) 289 

br_uint_32 BrTableRemoveMany (br_pixelmap* const* pixelmaps, int n) 290 

void BrTableUpdate (br_pixelmap* pixelmap, br_uint_16 flags) 289 

void BrTransformToMatrix34 (br_matrix34* mat, const br_transform* xform) 353 

void BrTransformToTransform(br_transform* dest, const br_transform* src) 353 

void BrVector2Accumulate(br_vector2* vl, const br_vector2* v2) 360 

void BrVector2Add(br_vector2* v1, const br_vector2* v2, const br_vector2* v3) 360 

void BrVector2Copy (br_vector2* vl, const br_vector2* v2) 364 

br_scalar BrVector2Dot (const br_vector2* v1, const br_vector2* v2) 362 

void BrVector2InvScale(br_vector2* v1, const br_vector2* v2, br_scalar s) 36] 

br_scalar BrVector2Length(const br_vector2* v1) 362 

br_scalar BrVector2LengthSquared(const br_vector2* v1) 363 

void BrVector2Negate (br_vector2* vl, const br_vector2* v2) 359 
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void BrVector2Normalise (br_vector2* v1, const br_vector2* v2) 363 

void BrVector2Scale(br_vector2* v1, const br_vector2* v2, br_scalar s) 36] 

void BrVector2Set (br_vector2* v1, br_scalar sl, br_scalar s2) 364 

void BrVector2SetFloat (br_vector2* v1, float £1, float £2) 365 

void BrVector2SetInt (br_vector2* vl, int il, int i2) 365 

void BrVector2Sub (br_vector2* v1, const br_vector2* v2, const br_vector2* v3) 36/ 

void BrVector3Accumulate (br_vector3* vl, const br_vector3* v2) 368 

void BrVector3Add (br_vector3* v1, const br_vector3* v2, const br_vector3* v3) 368 

void BrVector3Copy (br_vector3* vl, const br_vector3* v2) 373 

void BrVector3Cross (br_vector3* v1, const br_vector3* v2, const br_vector3* v3) 370 

br_scalar BrVector3Dot (const br_vector3* v1, const br_vector3* v2) 370 

void BrVector3InvScale(br_vector3* v1, const br_vector3* v2, br_scalar s) 370 

br_scalar BrVector3Length (const br_vector3* v1) 37] 

br_scalar BrVector3LengthSquared (const br_vector3* v1) 37] 

void BrVector3Negate (br_vector3* vl, const br_vector3* v2) 368 

void BrVector3Normalise (br_vector3* v1, const br_vector3* v2) 372 

void BrVector3NormaliseLP (br_vector3* v1, const br_vector3* v2) 373 

void BrVector3NormaliseQuick (br_vector3* v1, const br_vector3* v2) 372 

void BrVector3Scale(br_vector3* v1, const br_vector3* v2, br_scalar s) 369 

void BrVector3Set (br_vector3* v1, br_scalar sl, br_scalar s2, br_scalar s3) 374 

void BrVector3SetFloat (br_vector3* v1, float £1, float £2, float £3) 374 

void BrVector3SetInt (br_vector3* vl, int il, int i2, int i3) 375 

void BrVector3Sub (br_vector3* v1, const br_vector3* v2, const br_vector3* v3) 369 

void BrVector4Copy (br_vector4* vl, const br_vector4* v2) 377 

br_scalar BrVector4Dot (const br_vector4* v1, const br_vector4* v2) 376 

int BrWriteModeSet (int mode) 65 

void BrZbBegin(br_uint_8 colour_type, br_uint_8 depth_type) 28 

br_scalar BrZbDepthToScreenZ (br_uint_32 depth_z, const br_camera* camera) 30 

void BrZbEnd (void) 4/ 

void BrZbModelRender (br_actor* actor, br_model* model, const br_material* material, br_uint_8 style, int on_screen, int 
use_custom) 253 

br_renderbounds_cbfn* BrZbRenderBoundsCallbackSet (br_renderbounds_cbfn* new_cbfn) 39 

void BrZbSceneRender (br_actor* world, br_actor* camera, br_pixelmap* colour_buffer, br_pixelmap* depth_buffer) 34 

void BrZbSceneRenderAdd (br_actor* tree) 37 

void BrZbSceneRenderBegin (br_actor* world, br_actor* camera, br_pixelmap* colour_buffer, br_pixelmap* depth_buffer) 35 

void BrZbSceneRenderEnd (void) 38 

br_uint_32 BrZbScreenZToDepth(br_scalar sz, const br_camera* camera) 3/] 

br_order_table* BrZsActorOrderTableGet (const br_actor* actor) 90 

br_order_table* BrZsActorOrderTableSet (br_actor* actor, br_order_table* order_table) 90 

void BrZsBegin(br_uint_8 colour_type, void* primitive, br_uint_32 size) 28 

br_scalar BrZsDepthToScreenZ(br_scalar depth_z, const br_camera* camera) 32 

void BrZsEnd (void) 4/ 

void BrZsModelRender (br_actor* actor, br_model* model, const br_material* material, br_order_table* order_table, br_uint_8 
style, int on_screen, int use_custom) 254 

br_order_table* BrZsOrderTableAllocate (br_uint_16 size, br_uint_32 flags, br_uint_16 type) 270 

void BrZsClearOrderTable(br_order_table* order_table) 269 

void BrZsOrderTableFree (br_order_table* order_table) 27] 

void BrZsOrderTablePrimaryDisable() 269 

void BrZsOrderTablePrimaryEnable (br_order_table* order_table) 268 

void BrZsOrderTablePrimitiveInsert (br_order_table* order_table, br_primitive* primitive, br_uint_16 bucket) 267 

br_uint_16 BrZsPrimitiveBucketSelect (const br_scalar* z, br_uint_16 pr_type, br_scalar min_z, br_scalar max_z, br_uint_16 
ot_size, br_uint_16 ot_type) 3/8 

br_primitive_cbfn* BrZsPrimitiveCallbackSet (br_primitive_cbfn* new_cbfn) 40 

br_renderbounds_cbfn* BrZsRenderBoundsCallbackSet (br_renderbounds_cbfn* new_cbfn) 39 

void BrZsSceneRender (br_actor* world, br_actor* camera, br_pixelmap* colour_buffer) 35 

void BrZsSceneRenderAdd (br_actor* tree) 37 

void BrZsSceneRenderBegin (br_actor* world, br_actor* camera, br_pixelmap* colour_buffer) 36 

void BrZsSceneRenderEnd (void) 38 

br_scalar BrZsScreenZToDepth(br_scalar sz, const br_camera* camera) 33 
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Example Call-Back Functions 


br_uint_32 BR_CALLBACK CBFnActorEnum(br_actor* a, void* arg) /0] 

void BR_CALLBACK CBFnDiagFailure(const char* message) //6 

void BR_CALLBACK CBFnDiagWarning(const char* message) //7 

void BR_CALLBACK CBFnFileAdvance(br_size_t count, void* f) 38] 

br_uint_32 BR_CALLBACK CBFnFileAttributes (void) 382 

void BR_CALLBACK CBFnFileClose(void* £) 383 

int BR_CALLBACK CBFnFileEOF (const void* f£) 384 

int BR_CALLBACK CBFnFileGetChr(void* f£) 385 

br_size_t BR_CALLBACK CBFnFileGetLine(char* buf, br_size t buf_len, void* f£) 386 

void* BR_CALLBACK CBFnFileOpenRead(const char* name, br_size_t n_magics, br_mode_test_cbfn* mode_test, int* mode_result) 
387 

void* BR_CALLBACK CBnFileOpenWrite(const char* name, int mode) 389 

void BR_CALLBACK CBFnFilePutChr(int c, void* £) 390 

void BR_CALLBACK CBFnFilePutLine(const char* buf, void* f£) 39] 

br_size_t BR_CALLBACK CBFnFileRead(void* buf, br_size_t size, unsigned int nelems, void* f£) 392 

br_size_t BR_CALLBACK CBFnFileWrite(const void* buf, br_size_t size, unsigned int nelems, void* £) 393 

void* BR_CALLBACK CBFnMemAllocate(br_size_t size, br_uint_8 type) 394 

void BR_CALLBACK CBFnMemF ree (void* block) 396 

br_size_t BR_CALLBACK CBFnMemInquire (br_uint_8 type) 397 

void BR_CALLBACK CBFnModelCustom(br_actor* actor, br_model* model, const br_material* material, void* render_data, 
br_uint_8 style, int on_screen, const br_matrix34* model_to_view, const br_matrix4* model_to_screen) 25/ 

br_uint_32 BR_CALLBACK CBFnModelEnum(br_model* model, void* arg) 259 

br_model* BR_CALLBACK CBFnModelFind(const char* name) 260 

int BR_CALLBACK CBFnModelPick2D (br_model* model, const br_material* material, const br_vector3* ray pos, const br_vector3* 
ray_dir, br_scalar t, int face, int edge, int vertex, const br_vector3* p, const br_vector2* map, void* arg) 26] 

int BR_CALLBACK CBFnModeTest (const br_uint_8* magics, br_size_t n_magics) 23] 

int BR_CALLBACK CBFnPick2D(br_actor* a, const br_model* model, const br_material* material, const br_vector3* ray_pos, 
const br_vector3* ray dir, br_scalar t_near, br_scalar t_far, void* arg) 272 

int BR_CALLBACK CBFnPick3D(br_actor* a, const br_model* model, const br_material* material, const br_matrix34* transform, 
const br_bounds* bounds, void* arg) 275 

void BR_CALLBACK CBFnPrimitive (br_primitive* primitive, br_actor* actor, const br_model* model, const br_material* 
material, br_order_table* order_table, const br_scalar* z) 316 

void BR_CALLBACK CBFnRenderBounds (br_actor* actor, const br_model* model, const br_material* material, void* render_data, 
br_uint_8 style, const br_matrix4* model_to_screen, const br_int_32 bounds[4]) 326 

br_uint_32 BR_CALLBACK CBFnResClassEnum(br_resource_class* item, void* arg) 330 

br_resource_class* BR_CALLBACK CBFnResClassFind(const char* name) 33/ 

br_uint_32 BR_CALLBACK CBFnResEnum(void* vres, void* arg) 333 

void BR_CALLBACK CBFnResourceFree(void* res, br_uint_8 res_class, br_size_t size) 34] 

br_uint_32 BR_CALLBACK CBFnTableEnum(br_pixelmap* table, void* arg) 347 

br_pixelmap* BR_CALLBACK CBFnTableFind(const char* name) 348 
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